AG Studio Launch Week 🚀🚀🚀 28 Sep - 2 Oct 2026 🚀🚀🚀 Join now
AG Grid
Best JavaScript Grid in the World
AG Charts
Best JavaScript Charts in the World
AG Studio
Best JavaScript Dashboard in the World
Bryntum Gantt
Speed-tuned Gantt chart for project planning
Bryntum Scheduler
Resource scheduling timeline component
PROPRO
Bryntum Scheduler Pro
Scheduler with auto-scheduling and constraints
Bryntum Calendar
Flexible JavaScript event calendar
Bryntum Task Board
Kanban-style task board component
Search⌘ KCtrl K
What's New
Getting started
Quick StartKey FeaturesCommunity vs. Enterprise
AI Features
Skills
Core features
Specialised Charts
Org ChartQuadrant Chart
Series
BarLineAreaScatterBubblePieDonutCombinationBox PlotCandlestickOHLCHeatmapHistogramNightingaleRadar AreaRadar LineRadial BarRadial ColumnRange AreaRange BarWaterfallSunburstTreemapSankeyChordFunnelCone FunnelPyramid
Gauges
Radial GaugeLinear Gauge

JavaScript ChartsCrosshairs and Band Highlight

Version 14.2.0
Enterprise

Crosshairs and band highlights provide visual references on the chart to indicate specific values or categories.

Crosshairs show a reference line and corresponding axis value at a specific position, either following the mouse or snapping to a highlighted item. Band highlights emphasise the entire category band.

Enabling Crosshairs Copy Link

To enable the crosshair feature for a given axis, use the crosshair property on the axes options object as shown below:

{
    axes: {
        y: {
            type: 'number',
            crosshair: {
                enabled: true,
            },
        },
    },
}

Snap Copy Link

By default, the crosshair will snap to the position of the highlighted node.

This default behaviour can be modified by using the crosshair snap option. When snap is false, the crosshair will follow the mouse pointer rather than snapping to the highlighted item.

{
    axes: {
        x: {
            type: 'number',
            crosshair: {
                snap: false,
            },
        },
    },
}

Styles Copy Link

Crosshair styles such as stroke, strokeWidth and lineDash are customisable via AgCrosshairOptions.

{
    crosshair: {
        stroke: '#2b5c95',
        strokeWidth: 2,
        lineDash: [5, 10],
    },
}

Label Copy Link

The crosshair label will be displayed along the axis by default. The label can be removed via the crosshair label option as shown in the code snippet below:

{
    crosshair: {
        label: {
            enabled: false, // removes crosshair label
        },
    },
}

Label Position Copy Link

The label position relative to the crosshair can be modified using the xOffset and yOffset properties in crosshair.label options as shown below:

{
    crosshair: {
        label: {
            // positions label -55px to the right of the start of the crosshair line
            xOffset: -55,

            // positions label 40px down from the start of the crosshair line
            yOffset: 40,
        },
    },
}

Label Format Copy Link

The crosshair.label.formatter or crosshair.label.format properties can be used to format the crosshair label.

If a format string is not provided, the axis.label.formatter function or axis.label.format string will be used.

If neither is present, default formatting will be used: one granularity above axis tick fraction digits for number axes and no formatting for category axes.

In this example:

  • Clicking 'Remove formats' will remove both the axis and crosshair label formats, with both showing the default format.
  • Clicking 'Set axis.label.format' will add a format to the axis label. Both the axis and crosshair labels will use this format, unless a crosshair label format has been added.
  • Clicking 'Set crosshair.label.format' will add a format to the crosshair label. The crosshair labels will use this format, and the axis labels will be unaffected.

See Formatters Inheritance and Precedence for more details on how formatters are inherited and precedence rules.

Default Label Renderer Copy Link

The default crosshair label is customisable using the crosshair label renderer option as shown below:

{
    crosshair: {
        label: {
            // Add label renderer callback function to customise label styles and content
            renderer: labelRenderer,
        },
    },
}
  • The renderer is a callback function which receives the axis value and its fractionDigits used for formatting the value at the crosshair position.
  • It returns an object with the text value as well as style attributes including color, backgroundColor and opacity for the crosshair label:
const labelRenderer = ({ value, fractionDigits }) => {
    return {
        text: value.toFixed(fractionDigits),
        color: 'aliceBlue',
        backgroundColor: 'darkBlue',
        opacity: 0.8,
    };
};

The default label HTML element uses these CSS class names, which can be used to customise styling:

  • ag-charts-crosshair-label for the label itself
  • ag-charts-crosshair-label-content - for the label content

For example, to set the label element's border-radius to 15px, you would use a style configuration like so:

.ag-charts-crosshair-label {
    border-radius: 15px;
}

This is demonstrated in the example below:

Custom Label Renderer Copy Link

A completely custom label can be provided by using the renderer function to return a string representing HTML content:

const labelRenderer = ({ value, fractionDigits }) => {
    return `<div class="custom-crosshair-label custom-crosshair-label-arrow">
            ${value.toFixed(fractionDigits)}</div>`;
};

The renderer function receives a single object with the axis value and fractionDigits.

The effect of applying the renderer from the snippet above can be seen in the example below.

Note that:

  • The structure of the returned DOM is up to you.
  • The elements have custom CSS class attributes, but the default class names can also be used so that the label gets the default styling.
  • The styles for the elements are defined in the external styles.css file.

Band Highlight Copy Link

Band highlights shade the entire hovered category or date on the chart.

To enable the band highlight for a given axis, use the bandHighlight property in the axes options object.

{
    axes: {
        x: {
            type: 'category',
            bandHighlight: {
                enabled: true,
            },
        },
    },
}

In the above example:

  • Hovering the chart shows a gray band highlight for the hovered category.
  • Unlike crosshairs, band highlights do not render an additional label.
  • Band highlights are available for category, grouped-category, unit-time, and ordinal-time axes.

See the Band Highlight API Reference for more details on the available customisation options.

API Reference Copy Link

Properties available on the AgCrosshairOptions interface.

enabled boolean
Whether to show the crosshair.
snap boolean
When true, the crosshair snaps to the highlighted data point. By default this property is true.
stroke AgCssColorOrRef
The colour of the stroke for the lines. A colour string, or a theme-colour reference object.
strokeWidth PixelSize
The width in pixels of the stroke for the lines.
strokeOpacity Opacity
The opacity of the stroke for the lines.
lineDash PixelSize[]
Defines how the line stroke is rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, `[6, 3]` means dashes with a length of `6` pixels with gaps between of `3` pixels.
lineDashOffset PixelSize
The initial offset of the dashed line in pixels.
label AgCrosshairLabel<string, ContextDefault>
The crosshair label configuration

Properties available on the AgBandHighlightOptions interface.

enabled boolean
Whether to show the band highlight.
stroke AgCssColorOrRef
The colour of the stroke for the lines. A colour string, or a theme-colour reference object.
strokeWidth PixelSize
The width in pixels of the stroke for the lines.
strokeOpacity Opacity
The opacity of the stroke for the lines.
lineDash PixelSize[]
Defines how the line stroke is rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, `[6, 3]` means dashes with a length of `6` pixels with gaps between of `3` pixels.
lineDashOffset PixelSize
The initial offset of the dashed line in pixels.
fill AgColorType
The colour to use for the fill of the band. A colour string, or an object for a gradient, pattern, or image fill.
fillOpacity Opacity
The opacity of the fill for the band.