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.