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

Built-in user interactions can be disabled individually, or all at once:

// Disable pan interaction
chart.setMouseInteractionPan(false)

List of all user built-in user interactions (or methods which toggle them):

• setMouseInteractionPan
• setMouseInteractionRectangleFit
• setMouseInteractionRectangleZoom
• setMouseInteractionWheelZoom

// Disable all interactions
chart.setMouseInteractions(false)

Custom user interactions can be implemented using the Events API:

chart.onSeriesBackgroundMouseClick((_, event) => {
    console.log('user clicked series area', event)
})

Alter "zoom to fit" interaction

By default, XY charts trigger "rectangle zoom" interaction when dragging with left mouse button, and "zoom out" interaction when dragging with right mouse button. A common requirement is to either completely remove the "zoom out" interaction OR apply it via double clicking on series area:

// Remove default "zoom out" interaction, activated when dragging with right mouse button
chart.setMouseInteractionRectangleFit(false)

// Fit data to view when user double clicks on series area
chart.onSeriesBackgroundMouseDoubleClick(() => {
    chart.forEachAxis((axis) => axis.fit())
})

Swapping left / right mouse buttons

A common desire is to swap default interaction mouse buttons (left/right) in XY charts for panning, zooming and fitting. This can be done like so:

const lc = lightningChart({
    // LightningChartOptions
    overrideInteractionMouseButtons: {
        chartXYPanMouseButton: 0, // LMB
        chartXYRectangleZoomFitMouseButton: 2, // RMB
        axisXYPanMouseButton: 0, // LMB
        axisXYZoomMouseButton: 2, // RMB
    }
})
const chart = lc.ChartXY()

Touch gestures

Touch gestures can be tracked with separate events API:

• onSeriesBackgroundTouchStart
• onSeriesBackgroundTouchMove
• onSeriesBackgroundTouchEnd

Despite the slightly misleading method naming, these are connected to JS Pointer events. They work with pen/stylus and touch surfaces.

Below you can find an example of a custom multi-finger touch gesture:

// Disable default interactions
chart
    .setAutoCursorMode(AutoCursorModes.disabled)
    .setMouseInteractionPan(false)
    .setMouseInteractionRectangleFit(false)
    .setMouseInteractionRectangleZoom(false)
    .setMouseInteractionWheelZoom(false)

// Custom 2-finger "pinch" gesture
const activePointers: PointerEvent[] = []
chart.onSeriesBackgroundTouchStart((_, event) => {
    activePointers.push(event)
})
chart.onSeriesBackgroundTouchMove((_, event) => {
    if (activePointers.length === 2) {
        // For generic pinch gesture, this logic is triggered twice, 1 for each finger. The direction of fingers must be considered for right behavior.
        const centerLocationY = (activePointers[0].clientY + activePointers[1].clientY) / 2
        const zoomY = 0.05 * (event.clientY > centerLocationY ? -event.movementY : event.movementY)
        chart.forEachAxisY((axis) => {
            axis.setStopped(true).zoom((axis.getInterval().start + axis.getInterval().end) / 2, zoomY)
        })
        event.preventDefault()
    }
})
chart.onSeriesBackgroundTouchEnd((_, event) => {
    const i = activePointers.findIndex((item) => item.pointerId === event.pointerId)
    if (i >= 0) {
        activePointers.splice(i, 1)
    }
})

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.onSeriesBackgroundMouseClick((_, event) => {
    const locationAxis = chart.translateCoordinate(event, chart.coordsAxis)
})

Translating Axis coordinate to client

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

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)

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.