Class BarChart<CursorResultTableBackgroundType>

Add manually controlled Cursor object. These have exactly same functions as built-in cursors but they can be freely controlled by application logic.

 const cursor = chart.addCursor()

Styling works same as built-in cursors (e.g. setCursor).

Position is set using setPosition method and displayed content using setResultTable(table => table.setContent(...)) For more details, see Developer documentation > Features > Cursor > Manual cursors

Returns

Cursor object.

Add callback function to be triggered when specified event is fired.

 // Example syntax
 object.addEventListener('click', (event) => {
     console.log(event)
 })

Some classes also report extra information about the interacted object with the second parameter:

 // Most series share information about interacted data point
 series.addEventListener('click', (event, info) => {
     console.log(info)
 })

Optional third parameter allows registering event handlers that will automatically remove themselves after first trigger:

 // Example this listener will only fire once
 object.addEventListener('click', (event) => {})

Each class has its own list of supported events. Some events are from HTML standard (click, pointerdown, etc.), while others are own events from LightningChart JS (dispose, resize, etc.)

To find what events are available, you can try following:

• If your development environment has TypeScript enabled, just write addEventListener and see what possible event types the IDE suggests. These APIs are strongly typed, and even the callback event will be correctly typed.
• Otherwise, open the class section in API documentation and check out which interface K type parameter extends.

Permanently destroy the component.

To fully allow Garbage-Collection to free the resources used by the component, make sure to remove any references to the component and its children in application code.

let chart = ...BarChart()
let axisX = chart.getDefaultAxisX()
// Dispose Chart, and remove all references so that they can be garbage-collected.
chart.dispose()
chart = undefined
axisX = undefined

Returns

Object itself for fluent interface

Get reference to a particular BarChartBar. The match is done against the category of bars and optionally also with subCategory.

 // Example
 barChart.setData([
     { category: 'Category 1', value: 10 },
     { category: 'Category 2', value: 12 },
 ])
 const bar = barChart.getBar('Category 1')

 // Example, grouped bar chart
 barChart.setDataGrouped(
     ['Cat 1', 'Cat 2'],
     [
         { subCategory: 'Scat 1', values: [10, 20] },
         { subCategory: 'Scat 2', values: [5, 6] },
     ]
 )
 const bar = barChart.getBar('Cat 1', 'Scat 2')

This method throws an error if the Bar is not found or input arguments are ambiguous (for example, stacked bar chart and sub category wasn't supplied).

Returns

Reference to the BarChartBar with matching category.

Get reference to all currently existing BarChartBars.

Returns

Array with all existing BarChartBar references.

Get theme effect enabled on component or disabled.

A theme can specify an Effect to add extra visual oomph to chart applications, like Glow effects around data or other components. Whether this effect is drawn above a particular component can be configured using the setEffect method.

 // Example, disable theme effect from a particular component.
 Component.setEffect(false)

For the most part, theme effects are enabled by default on most components.

Theme effect is configured with effect property.

Returns

Boolean that describes whether drawing the theme effect is enabled around the component or not.

Get margin around each bar along category axis as percentage of the bar thickness. For example, 0.1 = on both left and right side of bar there is a 10% margin. Actual thickness of bar depends on chart size, but for 100 px bar that would be 10 px + 10 px margin.

Valid value range is between [0, 0.49].

Returns

Margin around each bar along category axis as percentage of bar thickness.

Get current category labels configuration.

Returns

BarChartCategoryLabels object or undefined if labels are hidden.

Get rounded-ness of corners.

Returns

Number or undefined.

Introduced in v7.0. API might be changed depending on user feedback.

Get reference to the built-in cursor object of the chart.

Returns

Generic cursor object.

Get active cursor formatter.

Returns

Cursor formatter.

Get current cursor behavior.

Returns

SolveNearestMode or undefined

Get state of automatic label fitting.

This is enabled by default.

Returns

true or false

Get label fitting margins.

Returns

Margins as pixels.

Get minimum size of Chart. Depending on the type of class this value might be automatically computed to fit different elements.

Returns

Vec2 minimum size or undefined if unimplemented

Get series of a chart

Returns

Array of series

Get current sorting configuration.

Returns

undefined or BarChartSorter.

Get current value labels configuration.

Returns

BarChartValueLabels object or undefined if labels are hidden.

Remove event listener added using addEventListener. The expected argument should be the exact same callback function that was supplied using addEventListener:

 // Basic example syntax
 const listener = () => {}
 obj.addEventListener('click', listener)
 obj.removeEventListener('click', listener)

 // Basic boilerplate of custom interaction when user drags on an object
 obj.addEventListener('pointerdown', (eventDown) => {
     let prevCoord = eventDown
     const handlePointerMove: LCJSInteractionEventListener<'pointermove'> = (eventMove) => {
         const delta = { x: eventMove.clientX - prevCoord.clientX, y: eventMove.clientY - prevCoord.clientY }
         prevCoord = eventMove
         console.log(delta, eventMove.clientX, eventMove.clientY)
     }
     const handlePointerUp: LCJSInteractionEventListener<'pointerup'> = (eventUp) => {
         window.removeEventListener('pointermove', handlePointerMove)
         window.removeEventListener('pointerup', handlePointerUp)
     }
     window.addEventListener('pointermove', handlePointerMove)
     window.addEventListener('pointerup', handlePointerUp)
 })

Enable/disable animation of bar category positions. This is enabled by default.

 // Example, disable category position animation.
 BarChart.setAnimationCategoryPosition(false)

Returns

Object itself.

Enable/disable animation of bar values. This is enabled by default.

 // Example, disable value animation.
 BarChart.setAnimationValues(false)

Returns

Object itself.

Disable/Enable all animations of the Chart.

Returns

Chart itself for fluent interface.

Set theme effect enabled on component or disabled.

A theme can specify an Effect to add extra visual oomph to chart applications, like Glow effects around data or other components. Whether this effect is drawn above a particular component can be configured using the setEffect method.

 // Example, disable theme effect from a particular component.
 Component.setEffect(false)

For the most part, theme effects are enabled by default on most components.

Theme effect is configured with effect property.

Returns

Object itself.

Set margin around each bar along category axis as percentage of the bar thickness. For example, 0.1 = on both left and right side of bar there is a 10% margin. Actual thickness of bar depends on chart size, but for 100 px bar that would be 10 px + 10 px margin.

Valid value range is between [0, 0.49].

 // Example, no margin between bars.
 BarChart.setBarsMargin(0)

 // Example, increased space between bars.
 BarChart.setBarsMargin(0.20)

Returns

Object itself.

Configure how category labels are displayed in the BarChart. To see all configuration options, see BarChartCategoryLabels.

To display labels inside or after bars, see setValueLabels.

 // Example, hide labels
 barChart.setCategoryLabels(undefined)

 // Example, change label color
 barChart.setCategoryLabels({
     labelFillStyle: new SolidFill({ color: ColorRGBA(255, 0, 0) })
 })

 // Example, change label font size. In this case, the previous label configuration is used as a reference so callback function is convenient.
 barChart.setCategoryLabels((labels) => ({
     labelFont: labels.labelFont.setSize(10)
 }))

 // Example, configure formatting
 barChart.setCategoryLabels({
     formatter: (info) => `${info.category} (${(info.value / 1000).toFixed(1)} k€)`,
 })

• To learn more of font configurations, see FontSettings.
• To learn more of fill style configurations, see FillStyle.
• To disable automatic label fitting, use setLabelFittingEnabled.

Returns

Object itself.

Configure rounded-ness of corners.

 obj.setCornerRadius(10)             // 10 px rounding radius
 obj.setCornerRadius(undefined)     // straight corners

Style chart cursor using a callback function. Available style APIs can depend on the type of chart.

 // Example syntax
 chart.setCursor((cursor) => cursor
     .setGridStrokeXStyle(new SolidLine({
         thickness: 1,
         fillStyle: new SolidFill({ color: ColorRGBA( 255, 0, 0 ) })
     }))
 )

See Cursor2D, CursorXY or Cursor3D for all available methods for configuring the cursor.

Example usage:

 // Example 1, disable Y Axis tick marker & grid line.
 chart.setCursor((cursor) => cursor
     .setTickMarkerYVisible(false)
     .setGridStrokeYStyle(emptyLine)
 )

 // Example 2, style cursor ResultTable.
 chart.setCursor((cursor) => cursor
     .setResultTable((resultTable) => resultTable
         .setOrigin(UIOrigins.LeftTop)
         .setTextFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
         .setTextFont((font) => font
             .setSize(12)
             .setFamily('sans-serif')
         )
         .setBackground((background) => background
             .setFillStyle(new SolidFill({ color: ColorRGBA(0, 0, 0, 0) }))
         )
     )
 )

 // Example 3, style cursor TickMarker X.
 chart.setCursor((cursor) => cursor
     .setTickMarkerX((tickMarker: UIPointableTextBox) => tickMarker
         .setTextFont((font) => font.setWeight('bold'))
         .setTextFillStyle(new SolidFill({ color: ColorRGBA(0, 255, 0) }))
         .setBackground((background) => background.setFillStyle(emptyFill).setStrokeStyle(emptyLine)),
     )
 )

Returns

Object itself for fluent interface.

Set cursor formatting, controlling the text displayed in built-in cursor.

 chart.setCursorFormatting((_, hit, hits) => {
     return [
         ['Cursor pointing at'],
         [hit.series], // returning a series will display the series color and its name automatically.
         ['X', '', hit.axisX.formatValue(hit.x)], // utilizing axis formatValue is useful for considering active zoom level and type of axis
         ['Y', '', hit.y.toFixed(2)], // empty string '' results in gap between cells
         [{ text: 'Example', font: { weight: 'bold' }, fillStyle: fillRed }] // any cell can also be styled individually
     ]
 })

Before overriding default cursor formatting, it is recommended to check if using setUnits or configuring Axis cursor formatting would be enough.

In order to use series specific data properties (e.g. Heatmap sample "intensity"), you should use type guards to assert the type of the SolveResult:

 // Example of using type guard in cursor formatter
 Chart.setCursorFormatting((chart, hit, hits) => {
     if (!isHitHeatmap(hit)) return undefined
     return [hit.intensity.toFixed(1)]
 })

More details in Developer documentation (Features > Cursor).

Returns

Object itself

Set cursor behavior. This affects both built-in cursor as well as any custom cursor connected using setCustomCursor.

For possible values see SolveNearestMode. Additionally, you can supply undefined value to disable cursor completely.

 // Example, show 1 nearest solve result only
 chart.setCursorMode('show-nearest')

 // Example, disable cursor
 chart.setCursorMode(undefined)

 // Example, enable interpolation
 chart.setCursorMode('show-all-interpolated')

Returns

Object itself

Connect a custom cursor to the chart. This has 2 effects:

1. The built-in cursor is disabled.
2. The provided callback function is called whenever the custom cursor should be updated, along with the data that the cursor should be pointing at.

Custom cursors are still affected by other cursor behavior controls such as:

• setCursorMode
• Series setCursorEnabled

The custom cursor can be anything defined by the user, such as:

• Using other LCJS means of displaying the cursor, like custom ticks, constant lines, text boxes, etc.
• Displaying a cursor using HTML/JS/CSS
• Displaying a cursor using UI framework, like Angular, React, Vue, Next, ...

 // Example of plugging in a custom cursor
 chart.setCustomCursor((event) => {
     if (event) {
         // Display custom cursor
     } else {
         // Hide custom cursor
     }
 })

Returns

Object itself

Set BarChart data, updating the visible bars.

This method signature takes in an array of objects with category and optional value properties.

 // Example usage
 barChart.setData([
     { category: 'Category 1', value: 10 },
     { category: 'Category 2', value: 12 },
 ])

In use cases with real-time updates, the recommended way to push value updates to existing bars is to call setData again.

See also: setDataStacked setDataGrouped

Returns

Object itself

Set BarChart data, updating the visible bars.

This method signature takes a single object that can have any number of keys. Each key is interpreted as a category, and the respective value as the bar value.

 // Example usage
 barChart.setData({
     'Category 1': 10,
     'Category 2': 12,
 })

In use cases with real-time updates, the recommended way to push value updates to existing bars is to call setData again.

See also: setDataStacked setDataGrouped

Returns

Object itself

Set BarChart data, updating the visible bars.

This method signature takes an array of numbers, where each number is a value for a bar. In this case, each bar is just assigned an automatic category like "Category 1".

 // Example usage
 barChart.setData([10, 12])

In use cases with real-time updates, the recommended way to push value updates to existing bars is to call setData again.

See also: setDataStacked setDataGrouped

Returns

Object itself

Set BarChart data, updating the visible bars.

This method signature takes in an array of strings as Categories, without any Values. It can be used to initialize the categories before data is available, for example to show the bars in a LegendBox:

 // Data is not yet available, but prepare legend.
 barChart.setData(categories)
 const legend = barChart.addLegendBox().add(barChart)

See also: setDataStacked setDataGrouped

Returns

Object itself

Set BarChart data, updating the visible bars. This method accepts data for a Grouped Bar Chart, displaying it as such.

 BarChart.setDataGrouped(
     ['category 1' , 'category 2'],
     [
         { subCategory: 'sub category 1', values: [1, 2] },
         { subCategory: 'sub category 2', values: [3, 4] },
         { subCategory: 'sub category 3', values: [5, 6] },
     ]
 )

See also: setData setDataStacked

Released to public beta in v5.1.0. May be reworked according to customer feedback and experiences.

Set BarChart data, updating the visible bars. This method accepts data for a Stacked Bar Chart, displaying it as such.

 BarChart.setDataStacked(
     ['category 1' , 'category 2'],
     [
         { subCategory: 'sub category 1', values: [1, 2] },
         { subCategory: 'sub category 2', values: [3, 4] },
         { subCategory: 'sub category 3', values: [5, 6] },
     ]
 )

See also: setData setDataGrouped

Released to public beta in v5.1.0. May be reworked according to customer feedback and experiences.

Enable or disable automatic label fitting.

This is enabled by default.

 // Example, disable automatic label fitting
 barChart.setLabelFittingEnabled(false)

Returns

Object itself.

Set label fitting margins. This is only relevant if label fitting is enabled setLabelFittingEnabled. This is true by default.

These margins describe extra space that is added around every labels collision box.

 // Example, configure specific fitting margin (10 pixels)
 barChart.setLabelFittingMargins(10)

// Example, configure non-symmetric margins
 barChart.setLabelFittingMargins({ left: 5, right: 5, top: 0, bottom: 0 })

Returns

Object itself.

Configure automatic sorting of bars.

The default value is BarChartSorting.Descending.

 // Example, disable sorting
 barChart.setSorting(BarChartSorting.None)

 // Example, ascending sorting
 barChart.setSorting(BarChartSorting.Ascending)

 // Example, descending sorting
 barChart.setSorting(BarChartSorting.Descending)

 // Example, alphabetical sorting
 barChart.setSorting(BarChartSorting.Alphabetical)

 // Example, custom sorting (ascending implementation)
 barChart.setSorting((a, b) => a.value - b.value)

Returns

Object itself.

Configure how value labels are displayed in the BarChart.

There are a handful of different value label positioning types in BarChart, which you can find in BarChartValueLabels. Labels can also be separately displayed before bars on the other side of category axis, see setCategoryLabels.

 // Example, hide labels
 barChart.setValueLabels(undefined)

 // Example, display value labels after bars
 barChart.setValueLabels({
     position: 'after-bar'
 })

 // Example, display value labels inside bars with black color
 barChart.setValueLabels({
     position: 'inside-bar',
     labelFillStyle: new SolidFill({ color: ColorRGBA(0, 0, 0) })
 })

 // Example, change label font size. In this case, the previous label configuration is used as a reference so callback function is convenient.
 barChart.setValueLabels((labels) => ({
     labelFont: labels.labelFont.setSize(10)
 }))

 // Example, configure formatting
 barChart.setValueLabels({
     formatter: (info) => `${info.category} (${(info.value / 1000).toFixed(1)} k€)`,
 })

• To learn more of font configurations, see FontSettings.
• To learn more of fill style configurations, see FillStyle.
• To disable automatic label fitting, use setLabelFittingEnabled.

Returns

Object itself.

Translate a coordinate in HTML client coordinate system to another coordinate system.

(1) bars coordinate system:

 BarChart.seriesBackground.addEventListener('click', event => {
     const locationBars = chart.translateCoordinate(event, chart.coordsBars)
     // locationBars tells the clicked location relative to Bar Chart value and category axes.
 })

(2) relative control coordinate system:

 const locationClient = { clientX: document.body.clientWidth * 0.2, clientY: document.body.clientHeight * 0.5 }
 const locationRelative = chart.translateCoordinate(locationClient, chart.coordsRelative)
 // locationRelative is in pixels relative to bottom left corner of the chart

Relative coordinates can be used for positioning LightningChart JS UI components:

 const textBox = chart.addUIElement(UIElementBuilders.TextBox, chart.coordsRelative)
     // Left bottom of TextBox is positioned 20 pixels right and 20 pixels up from charts bottom left corner
     .setOrigin(UIOrigins.LeftBottom)
     .setPosition({ x: 20, y: 20 })

NOTE: Currently coordinate translations can't be guaranteed to be in sync with latest updates to charts. For example, if you change axis interval, or add data to a series, you need to wait for 1 frame to be displayed before translateCoordinate will behave as expected.

 LineSeries.add(myData)
 requestAnimationFrame(() => {
     // translateCoordinate should now consider data added just now.
 })

Translate a coordinate in Bars coordinate system to another coordinate system.

(1) HTML client coordinate system:

 const locationBars = { iCategory: 0, value: 100 }
 const locationClient = chart.translateCoordinate(locationBars, chart.client)

Client coordinates can be used to absolute position HTML elements using CSS, for example.

 myHTMLElement.style.position = 'absolute'
 myHTMLElement.style.left = locationClient.clientX
 myHTMLElement.style.top = locationClient.clientY

(2) relative control coordinate system:

 const locationBars = { iCategory: 0, value: 100 }
 const locationRelative = chart.translateCoordinate(locationBars, chart.coordsRelative)
 // locationRelative is in pixels relative to bottom left corner of the chart

Relative coordinates can be used for positioning LightningChart JS UI components:

 const textBox = chart.addUIElement(UIElementBuilders.TextBox, chart.coordsRelative)
     // Left bottom of TextBox is positioned 20 pixels right and 20 pixels up from charts bottom left corner
     .setOrigin(UIOrigins.LeftBottom)
     .setPosition({ x: 20, y: 20 })