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 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.

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.

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.

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: force pan/rectangle zoom along both X and Y dimensions

chart.setUserInteractions({
    pan: {
        x: true,
        y: true
    },
    rectangleZoom: {
        x: true,
        y: true
    },
})

Example: swap left and right mouse buttons

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

Example: modify wheel zoom behavior with scrolling axis (zoom toward pointer, stop scrolling axis)

chart.setUserInteractions({
    zoom: {
        mode: 'toward-pointer',
        stopScroll: true,
    },
})

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

chart.setUserInteractions({
    restoreDefault: false,
    restorePrevious: {
        doubleClick: true,
        ctrl: {
            code: 'KeyZ',
        },
    },
})

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(...)

Example: pan X/Y with mouse wheel depending on ctrl/shift keys

1. on mouse wheel scroll: zoom
2. on mouse wheel scroll + shift: pan on X axis
3. on mouse wheel scroll + ctrl: pan on Y axis

chart.setUserInteractions({
    zoom: {
        shift: false,
        ctrl: false,
    },
    pan: {
        // lmb: {}, // <-- required on older versions than v8.1 due to a library bug
        wheel: false,
        shift: {
            wheel: { x: true, y: false },
        },
        ctrl: {
            wheel: { y: true, x: false },
        },
    },
})

For more generic information about user interactions, please see generic documentation about setUserInteractions.

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 section.

Axis

Please see common Axis section.

Legend

Please see common Legend section.

Positioning charts

Please see common Positioning charts section.

Color themes

Please see common Color themes section.