---
title: "Crosshairs and Band Highlight"
enterprise: true
framework: javascript
version: "14.1.0"
---

# Crosshairs and Band Highlight

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

```ts
import {
  AgCartesianChartOptions,
  AgCharts,
  AnimationModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CategoryAxisModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  NumberAxisModule,
  ContextMenuModule,
]);

const options: AgCartesianChartOptions = {
  data: getData(),
  title: {
    text: "World Population",
  },
  series: [
    {
      type: "line",
      yKey: "population",
      xKey: "year",
    },
  ],
  axes: {
    y: {
      type: "number",
      crosshair: {
        enabled: true,
      },
    },
    x: {
      type: "category",
      crosshair: {
        enabled: true,
      },
    },
  },
  tooltip: {
    enabled: false,
  },
  formatter: {
    y: ({ value }) => {
      return `${Number(value).toLocaleString("en-GB", {
        notation: "compact",
        maximumFractionDigits: 1,
      })}`;
    },
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);
```

[Live example: Enabling Crosshairs](https://www.ag-grid.com/charts/typescript/axes-crosshairs/examples/enabling-crosshairs)

## Enabling Crosshairs

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

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

## Snap

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.

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

#### Crosshair Snap False

```ts
import {
  AgCartesianChartOptions,
  AgCharts,
  AnimationModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CategoryAxisModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  NumberAxisModule,
  ContextMenuModule,
]);

const options: AgCartesianChartOptions = {
  data: getData(),
  title: {
    text: `United Kingdom Population`,
  },
  series: [
    {
      type: "line",
      yKey: "population",
      xKey: "year",
    },
  ],
  axes: {
    y: {
      type: "number",
      crosshair: {
        snap: false,
      },
    },
    x: {
      type: "category",
      title: {
        text: "Year",
      },
      crosshair: {
        snap: false,
      },
    },
  },
  tooltip: {
    enabled: false,
  },
  formatter: {
    y: ({ value }) => {
      return `${Number(value).toLocaleString("en-GB", {
        notation: "compact",
        maximumFractionDigits: 1,
      })}`;
    },
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);
```

[Live example: Crosshair Snap False](https://www.ag-grid.com/charts/typescript/axes-crosshairs/examples/crosshair-snap)

## Styles

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

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

#### Crosshair Styles

```ts
import {
  AgCartesianChartOptions,
  AgCharts,
  AnimationModule,
  BubbleSeriesModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  BubbleSeriesModule,
  CrosshairModule,
  LegendModule,
  NumberAxisModule,
  ContextMenuModule,
]);

const options: AgCartesianChartOptions = {
  data: getData(),
  series: [
    {
      type: "bubble",
      sizeKey: "planetRadius",
      sizeName: "Planet Radius",
      yKey: "eccentricity",
      yName: "Eccentricity",
      xKey: "distance",
      xName: "Distance",
    },
  ],
  axes: {
    y: {
      type: "number",
      title: {
        text: "Eccentricity",
      },
      crosshair: {
        stroke: "#2b5c95",
        strokeWidth: 2,
        lineDash: [5, 10],
      },
    },
    x: {
      type: "number",
      title: {
        text: "Distance [pc]",
      },
      crosshair: {
        stroke: "#2b5c95",
        strokeWidth: 2,
        lineDash: [5, 10],
      },
    },
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);
```

[Live example: Crosshair Styles](https://www.ag-grid.com/charts/typescript/axes-crosshairs/examples/crosshair-styles)

## Label

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:

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

### Label Position

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

```js
{
    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,
        },
    },
}
```

#### Crosshair Label Offset

```ts
import {
  AgCartesianChartOptions,
  AgCharts,
  AnimationModule,
  BubbleSeriesModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  BubbleSeriesModule,
  CrosshairModule,
  LegendModule,
  NumberAxisModule,
  ContextMenuModule,
]);

const options: AgCartesianChartOptions = {
  data: getData(),
  series: [
    {
      type: "bubble",
      sizeKey: "planetRadius",
      sizeName: "Planet Radius",
      yKey: "equilibriumTemp",
      yName: "Equilibrium Temperature",
      xKey: "planetRadius",
      xName: "Planet Radius",
    },
  ],
  axes: {
    y: {
      type: "number",
      title: {
        text: "Equilibrium Temperature [K]",
      },
      crosshair: {
        label: {
          xOffset: -55,
        },
      },
    },
    x: {
      type: "number",
      title: {
        text: "Planet Radius [Earth Radius]",
      },
      crosshair: {
        label: {
          yOffset: 40,
        },
      },
    },
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);
```

[Live example: Crosshair Label Offset](https://www.ag-grid.com/charts/typescript/axes-crosshairs/examples/crosshair-label-offset)

### Label Format

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.

#### Crosshair Label Format

```ts
import {
  AgCartesianChartOptions,
  AgCharts,
  AgUnitTimeAxisOptions,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  ModuleRegistry,
  NumberAxisModule,
  UnitTimeAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  NumberAxisModule,
  UnitTimeAxisModule,
  ContextMenuModule,
]);

const options: AgCartesianChartOptions = {
  data: getData(),
  animation: { enabled: false },
  series: [
    {
      type: "line",
      xKey: "year",
      yKey: "Onshore wind",
      yName: "Onshore Wind",
    },
    {
      type: "line",
      xKey: "year",
      yKey: "Offshore wind",
      yName: "Offshore Wind",
    },
    {
      type: "line",
      xKey: "year",
      yKey: "Solar photovoltaics",
      yName: "Solar Photovoltaics",
    },
    {
      type: "line",
      xKey: "year",
      yKey: "Small scale Hydro",
      yName: "Small Scale Hydro",
    },
  ],
  axes: {
    x: {
      type: "unit-time",
      crosshair: {
        enabled: true,
      },
    },
    y: {
      position: "right",
      type: "number",
      title: {
        text: `kilotonnes of oil equivalent (ktoe)`,
      },
      line: {
        enabled: false,
      },
      crosshair: {
        enabled: false,
      },
    },
  },
  tooltip: {
    enabled: false,
  },
  formatter: {
    y: (params) => `${(params.value as number) / 1000}K`,
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

function crosshairLabelFormat() {
  const crosshair = options.axes!.x!.crosshair! as AgUnitTimeAxisOptions;
  crosshair.label = {
    format: `%d %b '%y`,
  };

  chart.update(options);
}

function axisLabelFormat() {
  const axesX = options.axes!.x! as AgUnitTimeAxisOptions;
  const crosshair = axesX.crosshair!;
  if (crosshair.label && crosshair.label.format) {
    delete crosshair.label.format;
  }
  axesX.label = { format: `%b %Y` };

  chart.update(options);
}

function defaultFormat() {
  const axesX = options.axes!.x! as AgUnitTimeAxisOptions;
  const crosshair = axesX.crosshair!;
  if (crosshair.label && crosshair.label.format) {
    delete crosshair.label.format;
  }
  if (axesX.label && axesX.label.format) {
    delete axesX.label!.format;
  }

  chart.update(options);
}

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).crosshairLabelFormat = crosshairLabelFormat;
  (<any>window).axisLabelFormat = axisLabelFormat;
  (<any>window).defaultFormat = defaultFormat;
}
```

[Live example: Crosshair Label Format](https://www.ag-grid.com/charts/typescript/axes-crosshairs/examples/crosshair-label-format)

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](https://www.ag-grid.com/charts/javascript/formatters/#inheritance-and-precedence) for more details on how formatters are inherited and precedence rules.

### Default Label Renderer

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

```js
{
    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:

```js
const labelRenderer = ({ value, fractionDigits }) => {
    return {
        text: value.toFixed(fractionDigits),
        color: 'aliceBlue',
        backgroundColor: 'darkBlue',
        opacity: 0.8,
    };
};
```

#### Crosshair Default Label With Custom Renderer

```ts
import {
  AgCartesianChartOptions,
  AgCharts,
  AgCrosshairLabelRendererParams,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  HistogramSeriesModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
  TimeAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

const crosshairLabelRenderer = ({ value }: AgCrosshairLabelRendererParams) => {
  return {
    text: `${(value / 1000000).toFixed(1)}M`,
    color: "aliceBlue",
    backgroundColor: "darkBlue",
    opacity: 0.8,
  };
};
ModuleRegistry.registerModules([
  AnimationModule,
  CrosshairModule,
  HistogramSeriesModule,
  LegendModule,
  NumberAxisModule,
  TimeAxisModule,
  ContextMenuModule,
]);

const options: AgCartesianChartOptions = {
  data: getData(),
  series: [
    {
      type: "histogram",
      yKey: "bicycleHires",
      yName: "Bicycle Hires",
      xKey: "day",
      xName: "Day",
    },
  ],
  axes: {
    y: {
      type: "number",
      position: "right",
      title: {
        text: "Number of Bicycle Hires",
      },
      crosshair: {
        label: {
          xOffset: 50,
          renderer: crosshairLabelRenderer,
        },
      },
    },
    x: {
      type: "time",
      crosshair: {
        label: {
          format: `%b %d`,
        },
      },
    },
  },
  formatter: {
    y: (params) => `${(params.value as number) / 1000000}M`,
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);
```

[Live example: Crosshair Default Label With Custom Renderer](https://www.ag-grid.com/charts/typescript/axes-crosshairs/examples/crosshair-default-label-custom-renderer)

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:

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

This is demonstrated in the example below:

#### Crosshair Default Label With Custom CSS

```ts
import {
  AgCartesianChartOptions,
  AgCharts,
  AnimationModule,
  BubbleSeriesModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  BubbleSeriesModule,
  CrosshairModule,
  LegendModule,
  NumberAxisModule,
  ContextMenuModule,
]);

const options: AgCartesianChartOptions = {
  data: getData(),
  series: [
    {
      type: "bubble",
      sizeKey: "planetRadius",
      sizeName: "Planet Radius",
      yKey: "equilibriumTemp",
      yName: "Equilibrium Temperature",
      xKey: "planetRadius",
      xName: "Planet Radius",
    },
  ],
  axes: {
    y: {
      type: "number",
      position: "right",
      title: {
        text: "Equilibrium Temperature [K]",
      },
      crosshair: {
        label: {
          xOffset: 50,
        },
      },
    },
    x: {
      type: "number",
      title: {
        text: "Distance [pc]",
      },
      crosshair: {
        label: {
          yOffset: 35,
        },
      },
    },
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);
```

[Live example: Crosshair Default Label With Custom CSS](https://www.ag-grid.com/charts/typescript/axes-crosshairs/examples/crosshair-default-label-custom-css)

### Custom Label Renderer

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

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

#### Crosshair Custom Label

```ts
import {
  AgCartesianChartOptions,
  AgCharts,
  AgCrosshairLabelRendererParams,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

const crosshairLabelRenderer = (arrowPosition: "top" | "right") => {
  const classList =
    arrowPosition === "top"
      ? "secondary-axes-crosshair-label crosshair-label-arrow-top"
      : "secondary-axes-crosshair-label crosshair-label-arrow-right";
  return ({ value, fractionDigits }: AgCrosshairLabelRendererParams) => {
    return `<div class='${classList}'>
            <div>${value.toFixed(fractionDigits)}</div>
         </div>`;
  };
};
const data = getData();
const buildSeries = () => {
  return Object.entries(data[0])
    .filter(([key]) => key !== "All fuels" && key !== "year")
    .map(([key]) => ({
      type: "line" as const,
      xKey: "year",
      yKey: key,
    }));
};
ModuleRegistry.registerModules([
  AnimationModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  NumberAxisModule,
  ContextMenuModule,
]);

const options: AgCartesianChartOptions = {
  data,
  series: buildSeries(),
  axes: {
    y: {
      type: "number",
      title: {
        text: "Kilotonnes of Oil Equivalent",
      },
      crosshair: {
        snap: false,
        label: {
          renderer: crosshairLabelRenderer("right"),
        },
      },
    },
    x: {
      type: "number",
      crosshair: {
        snap: false,
        label: {
          renderer: crosshairLabelRenderer("top"),
        },
      },
    },
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);
```

[Live example: Crosshair Custom Label](https://www.ag-grid.com/charts/typescript/axes-crosshairs/examples/crosshair-custom-label)

## Band Highlight

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

#### Band Highlighting

```ts
import {
  AgCartesianChartOptions,
  AgCharts,
  AnimationModule,
  BandHighlightModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  BandHighlightModule,
  CategoryAxisModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  NumberAxisModule,
  ContextMenuModule,
]);

const options: AgCartesianChartOptions = {
  data: getData(),
  title: {
    text: `United Kingdom Population`,
  },
  series: [
    {
      type: "line",
      yKey: "population",
      xKey: "year",
    },
  ],
  axes: {
    y: {
      type: "number",
      crosshair: {
        enabled: false,
      },
    },
    x: {
      type: "category",
      title: {
        text: "Year",
      },
      bandHighlight: {
        enabled: true,
      },
    },
  },
  formatter: {
    y: ({ value }) => {
      return `${Number(value).toLocaleString("en-GB", {
        notation: "compact",
        maximumFractionDigits: 1,
      })}`;
    },
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);
```

[Live example: Band Highlighting](https://www.ag-grid.com/charts/typescript/axes-crosshairs/examples/band-highlight)

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

```js
{
    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](#reference-AgBandHighlightOptions) for more details on the available customisation options.

## API Reference

#### Crosshair

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| 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 | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | 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 |

#### Band Highlight

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| enabled | boolean |  | Whether to show the band highlight. |
| stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | 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 | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor \| AgGradientColor \| AgPatternColor \| AgImageFill |  | 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. |