---
title: "Crosshairs and Band Highlight"
enterprise: true
framework: angular
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
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Enabling Crosshairs](https://www.ag-grid.com/charts/angular/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
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Crosshair Snap False](https://www.ag-grid.com/charts/angular/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
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Crosshair Styles](https://www.ag-grid.com/charts/angular/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
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Crosshair Label Offset](https://www.ag-grid.com/charts/angular/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
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Crosshair Label Format](https://www.ag-grid.com/charts/angular/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/angular/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
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Crosshair Default Label With Custom Renderer](https://www.ag-grid.com/charts/angular/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
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Crosshair Default Label With Custom CSS](https://www.ag-grid.com/charts/angular/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
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

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

## Band Highlight

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

#### Band Highlighting

```ts
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Band Highlighting](https://www.ag-grid.com/charts/angular/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. |