Skip to main content
Version: 6.1.2

XY Chart

ChartXY is a collection of series, axes and other chart components. It can be used to create an incredible number of different data visualization elements.

// Creation of ChartXY
const lc = lightningChart()
const chart = lc.ChartXY()

Chart with line series Chart with line series

Chart title​

chart
    .setTitle('Voltage')
    .setTitleFont(font => font.setSize(10).setFamily('Segoe UI'))
    .setTitleFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
    .setTitlePosition('series-left-top')

For more details about style API, please see Styles, colors and fonts](/6.1.2/more-guides/styles-colors-and-fonts).

Background style​

ChartXY has 3 different levels of backgrounds:

  • Series background (area enclosed by axes)
  • Chart background (entire chart area)
  • Engine background (additional background shared by entire engine)
    • Understanding difference between chart/engine background is mainly useful if you are using the legacy Dashboard feature - in this case, engine background is shared across the whole dashboard.
chart
    .setBackgroundFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
    .setSeriesBackgroundFillStyle(new SolidFill({ color: ColorRGBA(0, 255, 0) }))
    .setSeriesBackgroundStrokeStyle(new SolidLine({ thickness: 1, fillStyle: new SolidFill({ color: ColorRGBA(0, 0, 255) }) }))
chart.engine.setBackgroundFillStyle(new SolidFill({ color: ColorRGBA(0, 0, 255) }))

For more details about style API, please see Styles, colors and fonts](/6.1.2/more-guides/styles-colors-and-fonts).

Space around chart​

chart.setPadding({ left: 10, right: 10, top: 10, bottom: 10 })

Disable animations​

const chart = lc.ChartXY({ animationsEnabled: false })

User interactions​

XY chart user interactions can be configured with setUserInteractions method. Here you can find a handful of most commonly required examples. For more information, please see generic documentation about setUserInteractions](/6.1.2/features/user-interactions).

At time of writing, ChartXY comes with following set of available built-in user interactions:

  • Panning (by dragging mouse, using mouse wheel or via pinch with touch devices)
  • Zooming (by dragging mouse, using mouse wheel or via pinch with touch devices)
  • Rectangle zooming (mouse/stylus/touch)
  • Restore default view (double click or keyboard)
  • Restore previous view (double click or keyboard)
  • Pagination (keyboard)

Example: disable all user interactions​

chart.setUserInteractions(undefined)

Example: swap left and right mouse buttons​

chart.setUserInteractions({
    pan: {
        lmb: { drag: {} },
        rmb: false,
    },
    rectangleZoom: {
        lmb: false,
        rmb: {},
    },
})

Example: switch "restore default view" to "restore previous view"​

chart.setUserInteractions({
    restoreDefault: false,
    restorePrevious: {
        doubleClick: true,
        ctrlZ: true,
    },
})

Example: Mouse wheel pan on Y axis​

Above examples mostly configure interactions directly inside chart area. A different set of interactions can be defined for xAxis and yAxis, or for both using axes.

chart.setUserInteractions({
    yAxis: {
        pan: {
            wheel: {},
        },
        zoom: { wheel: false },
    },
})

It is also possible to configure different set of interactions for two different axes, even if both are Y for example:

axis1.setUserInteractions(...)
axis2.setUserInteractions(...)

For more information about user interactions, please see generic documentation about setUserInteractions](/6.1.2/features/user-interactions).

Coordinate translations​

LightningChartJS has a number of different coordinate systems that are not natively present on a web page - most importantly, the charts Axes.

In many data visualization use cases it is critical to add annotations or markers at specific coordinates along the Axes and data series. Because of this, the ability to translate between coordinates on the web page and the axes is critical.

In this context, "client" refers to the Web API Client coordinate system.

Translating client coordinate to Axis​

chart.seriesBackground.addEventListener('click', event => {
    const locationAxis = chart.translateCoordinate(event, chart.coordsAxis)
})
info

chart.coordsAxis is a shorthand for { x: chart.axisX, y: chart.axisY }

Translating Axis coordinate to client​

const locationAxis = { x: 0, y: 0 }
const locationClient = chart.translateCoordinate(locationAxis, chart.coordsAxis, chart.coordsClient)
info

chart.coordsAxis is a shorthand for { x: chart.axisX, y: chart.axisY }

Relative coordinate system​

Apart from the widely used "axis" and "client" coordinate system, there is another, the "relative" coordinate system. This is mostly utilized for LightningChart UI components that are positioned as pixel locations relative to the chart (e.g. 10 pixels from left edge etc.).

// Example, translate axis to relative coordinate
const locationAxis = { x: 0, y: 0 }
const locationRelative = chart.translateCoordinate(locationAxis, chart.coordsAxis, chart.coordsRelative)

Fixed aspect ratio​

In some use cases, the visible ratio between X and Y axes must have a specific value (e.g. 1/2). While it is easy to fix a ratio between the width and height of the chart container using CSS, this doesn't directly correlate to the area enclosed by axes.

Within a ChartXY the are concepts such as chart titles, axis titles and axis ticks which can use some space within the chart. To realize a fixed aspect ratio, you have to consider these as well.

For purposes of fixed aspect ratio use cases, there is a convenience API: ChartXYLayoutChangedEvent. This doesn't directly set an aspect ratio, but instead gives information about the dimensions and layout within the chart which can be used to get a fixed aspect ratio.

The most common way of doing this is to allocate extra width/height to chart paddings in order to fix the aspect ratio of axes area:

// Example: Fixed aspect ratio, extra space is allocated as chart padding
const aspectRatio = 1 // width / height
chart.addEventListener('layoutchange', (layout) => {
    const spaceAvailable = { x: layout.viewportWidth + chart.getPadding().right, y: layout.viewportHeight + chart.getPadding().bottom }
    // Fit desired aspect ratio within space available in chart.
    let width
    let height
    if (spaceAvailable.x / spaceAvailable.y > aspectRatio) {
        height = spaceAvailable.y
        width = height * aspectRatio
    } else {
        width = spaceAvailable.x
        height = width / aspectRatio
    }
    chart.setPadding({
        right: chart.getPadding().right + (layout.viewportWidth - width) + 10,
        bottom: chart.getPadding().bottom + (layout.viewportHeight - height) + 10,
    })
})

Cursors​

Please see common Cursors](/6.1.2/features/cursor) section.

Axis​

Please see common Axis](/6.1.2/features/axis) section.

Legend​

Please see common Legend](/6.1.2/features/legend) section.

Positioning charts​

Please see common Positioning charts](/6.1.2/more-guides/positioning-charts) section.

Color themes​

Please see common Color themes](/6.1.2/more-guides/themes) section.