Cursor

LightningChart JS has a built in Cursor functionality. This is activated when user places mouse over a chart, displaying information about the pointed chart component.

The cursor functionality can be customized in many ways. Please note that the available functionality and API syntax varies between chart and series types!

Enabling/disabling cursor

// Disable cursor
Chart.setAutoCursorMode(AutoCursorModes.disabled)

// Enable cursor
Chart.setAutoCursorMode(AutoCursorModes.snapToClosest)

// Enable cursor when its directly above a chart component
Chart.setAutoCursorMode(AutoCursorModes.onHover)

Configuring result table

Text color and font

chart.setAutoCursor((cursor) => cursor
    .setResultTable((resultTable) => resultTable
        .setTextFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
        .setTextFont((font) => font.setWeight('bold'))
    )
)

For more details about style API, please see Styles, colors and fonts.

Configuring text font and color separately for different content inside result table is also possible. This API syntax depends on the chart type. For example, see Result table formatting in ChartXY

Background fill and border

chart.setAutoCursor((cursor) => cursor
    .setResultTable((resultTable) => resultTable
        .setBackground((background) => background
            .setFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
            .setStrokeStyle(new SolidLine({ thickness: 1, fillStyle: new SolidFill({ color: ColorRGBA(0, 255, 0) }) }))
        )
    )
)

For more details about style API, please see Styles, colors and fonts.

Configuring point marker

By default, cursors display a small crosshair at pointed location.

Hide point marker

chart.setAutoCursor((cursor) => cursor
    .setPointMarkerVisible(false)
)

Shape, size and color

chart.setAutoCursor((cursor) => cursor
    .setPointMarker((pointMarker) => pointMarker
        .setShape(PointShape.Circle)
        .setSize({ x: 5, y: 5 })
        .setFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
    )
)

For more details about style API, please see Styles, colors and fonts.

Cursors in XY Chart

Result table formatting

Result table content is configured per-series, using setCursorResultTableFormatter method:

PointLineAreaSeries.setCursorResultTableFormatter((builder, series, sample) => builder
    .addRow('Pointing at', '', `X = ${x.toFixed(0)}`)
    .addRow(`Series = ${series.getName()}`)
    .addRow(`Y = ${series.axisY.formatValue(sample.y)}`)
)

In the above example, Axis.formatValue method is used to lean on default formatting of data points based on axis type and zoom range. Alternatively, you can specify completely custom formatting for the cursor, like with x.toFixed(0).

Each series type has its own type definition for setCursorResultTableFormatter method! If your development environment has no type intellisense, confirm that you are using the correct syntax from the API reference.

// More complicated syntax example, with if checks
PointLineAreaSeries.setCursorResultTableFormatter((builder, series, sample) => {
    builder.addRow('Hello')
    if (sample.y > 0) {
        builder.addRow('Y above 0')
    } else {
        builder.addRow('Y not above 0')
    }
    return builder
})

Each part of text in result table can have its own font and color. To do this, instead of string, supply object with some properties from text, font and fillStyle:

// Example of different fonts within result table content 
PointLineAreaSeries.setCursorResultTableFormatter((builder, series, sample) => builder
    .addRow({ text: series.axisX.getTitle(), font: { weight: 'bold' } }, '', series.axisX.formatValue(sample.x))
    .addRow({ text: series.axisY.getTitle(), font: { weight: 'bold' } }, '', series.axisY.formatValue(sample.y)),
)

If you need to show custom data values (not x, not y, not value, etc.) in result table, see separate guide on Custom sample properties.

Icons can also be shown in result table content:

const image = new Image()
image.src = 'my-image.png'
const icon = chart.engine.addCustomIcon(image)
PointLineAreaSeries.setCursorResultTableFormatter((builder, series, sample) => builder
    .addRow(icon)
    .addRow({ icon, fillStyle: new SolidFill({ color: ColorRGBA(255, 0, 0) }) })
)

Solve nearest basis

By default, nearest data point is solved by considering only distance along X-axis. This can be configured per-series:

LineSeries.setCursorSolveBasis('nearest-x')
LineSeries.setCursorSolveBasis('nearest-y')
LineSeries.setCursorSolveBasis('nearest')

Cursor interpolation

By default, cursors snap to the closest real data point. Alternatively, automatic interpolation can be enabled to display interpolated data value at cursor location:

PointLineAreaSeries.setCursorInterpolationEnabled(true)

Disable cursor from series

PointLineAreaSeries.setCursorEnabled(false)

Format tick marker text

The text displayed by tick markers is formatted according to the respective axes' tick strategy. To specify formatting, use Axis.setTickStrategy method:

axis.setTickStrategy(AxisTickStrategies.Numeric, (ticks) => ticks
    .setCursorFormatter((value) => `${value.toFixed(1)} C`)
)

Hide tick markers

chart.setAutoCursor((cursor) => cursor
    .setTickMarkerXVisible(false)
    .setTickMarkerYVisible(false)
)

Style tick marker text

chart.setAutoCursor((cursor) => cursor
    .setTickMarkerY((tickMarker) => tickMarker
        .setTextFont((font) => font.setSize(10))
        .setTextFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
        .setTextRotation(0)
    )
)

For more details about style API, please see Styles, colors and fonts.

Style tick marker background

chart.setAutoCursor((cursor) => cursor.setTickMarkerY((tickMarker) =>
    hasUIElementBackground(tickMarker) &&
    tickMarker.setBackground((background) => background
        .setFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
        .setStrokeStyle(new SolidLine({ thickness: 1, fillStyle: new SolidFill({ color: ColorRGBA(0, 255, 0) }) }))
    )
))

For more details about style API, please see Styles, colors and fonts.

Hide grid lines

chart.setAutoCursor((cursor) => cursor
    .setGridStrokeXStyle(emptyLine)
    .setGridStrokeYStyle(emptyLine)
)

Style grid lines

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

For more details about style API, please see Styles, colors and fonts.

Multi-series cursors

If your use case requires cursor with multi-series tracking (showing multiple series values at same time), please contact us.

Cursors in Polar Chart

Result table formatting

Result table content is configured per-series, using setCursorResultTableFormatter method:

PolarSeries.setCursorResultTableFormatter((builder, series, angleDeg, amplitude, format) => builder
    .addRow(`${series.getName()}`)
    .addRow('Angle', '', `${Math.round(angleDeg)} °`)
    .addRow('Amplitude', '', `${format(amplitude)}`),
)

In the above example, Axis.formatValue method is used to lean on default formatting of data points based on axis type and zoom range. Alternatively, you can specify completely custom formatting for the cursor, like amplitude.toFixed(0).

Each series type has its own type definition for setCursorResultTableFormatter method! If your development environment has no type intellisense, confirm that you are using the correct syntax from the API reference.

// More complicated syntax example, with if checks
PolarSeries.setCursorResultTableFormatter((builder, series, angleDeg, amplitude, format) => {
    builder.addRow('Hello')
    if (amplitude > 0) {
        builder.addRow('amplitude above 0')
    } else {
        builder.addRow('amplitude not above 0')
    }
    return builder
})

Each part of text in result table can have its own font and color. To do this, instead of string, supply object with some properties from text, font and fillStyle:

// Example of different fonts within result table content 
PolarSeries.setCursorResultTableFormatter((builder, series, angleDeg, amplitude, format) => builder
    .addRow({ text: series.getName(), font: { weight: 'bold' } }, '', format(amplitude))
)

Icons can also be shown in result table content:

const image = new Image()
image.src = 'my-image.png'
const icon = chart.engine.addCustomIcon(image)
PointLineAreaSeries.setCursorResultTableFormatter((builder, series, sample) => builder
    .addRow(icon)
    .addRow({ icon, fillStyle: new SolidFill({ color: ColorRGBA(255, 0, 0) }) })
)

Cursor interpolation

Some Polar series support cursor interpolation (at least Polar heatmap series). If this is not desirable, it can be disabled with series setCursorInterpolationEnabled method:

PolarHeatmapSeries.setCursorInterpolationEnabled(false)

Disable cursor from series

PolarSeries.setCursorEnabled(false)

For more details about style API, please see Styles, colors and fonts.

Cursors in Bar Chart

Result table content is configured for whole BarChart, using BarChart.setCursorResultTableFormatter method:

chart.setCursorResultTableFormatter((builder, category, value, bar) => builder
    .addRow(category)
    .addRow(bar.chart.valueAxis.formatValue(value))
)

In the above example, Axis.formatValue method is used to lean on default formatting of data points based on axis type and zoom range. Alternatively, you can specify completely custom formatting for the cursor, like value.toFixed(0).

// More complicated syntax example, with if checks
chart.setCursorResultTableFormatter((builder, category, value, bar) => {
    builder.addRow('Hello')
    if (value > 0) {
        builder.addRow('Value above 0')
    } else {
        builder.addRow('Value not above 0')
    }
    return builder
})

Each part of text in result table can have its own font and color. To do this, instead of string, supply object with some properties from text, font and fillStyle:

// Example of different fonts within result table content 
chart.setCursorResultTableFormatter((builder, category, value, bar) => builder
    .addRow({ text: category, font: { weight: 'bold' } })
    .addRow(bar.chart.valueAxis.formatValue(value)),
)

Cursors in 3D Chart

Chart3D currently has no built-in cursor functionality. If your use case requires 3D cursors, then please get in touch and we'll arrange it.

Cursors in Funnel Chart

Cursor formatting is configured with FunnelChart.setCursorResultTableFormatter method:

funnelChart
    .setCursorResultTableFormatter((builder, chart, slice, relativeValue) => builder
        .addRow('Pointing at')
        .addRow(slice.getName())
        .addRow('Value:', '', slice.getValue().toFixed(1))
    )

Cursors in Pie Chart

Cursor formatting is configured with PieChart.setCursorResultTableFormatter method:

pieChart
    .setCursorResultTableFormatter((builder, chart, slice, relativeValue) => builder
        .addRow('Pointing at')
        .addRow(slice.getName())
        .addRow('Value:', '', slice.getValue().toFixed(1))
    )

Cursors in Pyramid Chart

Cursor formatting is configured with PyramidChart.setCursorResultTableFormatter method:

pyramidChart
    .setCursorResultTableFormatter((builder, chart, slice, relativeValue) => builder
        .addRow('Pointing at')
        .addRow(slice.getName())
        .addRow('Value:', '', slice.getValue().toFixed(1))
    )

Cursors in Spider Chart

Result table content is configured per-series, using SpiderSeries.setCursorResultTableFormatter method:

spiderSeries.setCursorResultTableFormatter((builder, series, value, axis, formatValue) => builder
    .addRow(series.getName())
    .addRow(axis)
    .addRow(formatValue(value))
)

Each part of text in result table can have its own font and color. To do this, instead of string, supply object with some properties from text, font and fillStyle:

// Example of different fonts within result table content 
spiderSeries.setCursorResultTableFormatter((builder, series, value, axis, formatValue) => builder
    .addRow({ text: series.getName(), font: { weight: 'bold' } })
)

Cursors in Map Chart

Cursor formatting can be configured with MapChart.setCursorResultTableFormatter method. formatLongitudeLatitude function is available for displaying longitude and latitude coordinates.

mapChart.setCursorResultTableFormatter((builder, region, value, longitude, latitude) => {
    builder.addRow(region.name).addRow(formatLongitudeLatitude(longitude, latitude))
    if (value) {
        builder.addRow(`Population: `, '', `${(value / (1000 * 1000)).toFixed(1)} million`)
    } else {
        builder.addRow(`No population data available`)
    }
    return builder
})

Custom cursors

The default cursors in LightningChart JS are fairly simple in terms of visual options (for example, rounded borders are not supported), and currently only allow tracking 1 series in 1 chart at a time. When advanced CSS styling is needed, the recommended approach is to implement a custom cursor.