---
title: "Series Highlighting"
framework: react
version: "14.1.0"
---

# Series Highlighting

Highlighting the hovered data item or series allows for easier differentiation, especially in charts with many series and data points.

#### Simple Highlight

```tsx
import React, { useState } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgChartOptions,
  BarSeriesModule,
  CategoryAxisModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";
import { getData } from "./data";

ModuleRegistry.registerModules([
  BarSeriesModule,
  CategoryAxisModule,
  LegendModule,
  NumberAxisModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgChartOptions>({
    data: getData(),
    title: {
      text: "Station Entries",
    },
    subtitle: {
      text: "Victoria Line (2023)",
    },
    series: [
      {
        type: "bar",
        xKey: "station",
        yKey: "early",
        yName: "Early",
        stacked: true,
        normalizedTo: 100,
      },
      {
        type: "bar",
        xKey: "station",
        yKey: "morningPeak",
        yName: "Morning Peak",
        stacked: true,
        normalizedTo: 100,
      },
      {
        type: "bar",
        xKey: "station",
        yKey: "interPeak",
        yName: "Inter-peak",
        stacked: true,
        normalizedTo: 100,
      },
      {
        type: "bar",
        xKey: "station",
        yKey: "afternoonPeak",
        yName: "Afternoon Peak",
        stacked: true,
        normalizedTo: 100,
      },
      {
        type: "bar",
        xKey: "station",
        yKey: "evening",
        yName: "Evening",
        stacked: true,
        normalizedTo: 100,
      },
    ],
  });

  return <AgCharts options={options} />;
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);
```

[Live example: Simple Highlight](https://www.ag-grid.com/charts/reactFunctionalTs/series-highlighting/examples/stacked-bars)

In the above example:

- Hovering a bar segment will highlight it. The other segments in that series are partially dimmed.
- Hovering a bar segment in one series will dim the other series.
- Hovering a legend item will dim the other series.

Highlighting is enabled by default. Use `highlight.enabled` to configure it globally, or `series[].highlight.enabled` to override it per series.

## Bring to Front

By default, the highlighted series is brought to the front to make it stand out, especially when multiple series overlap.

#### Bring to Front

```tsx
import React, { useState, Fragment } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgAreaSeriesOptions,
  AgCartesianChartOptions,
  AreaSeriesModule,
  CategoryAxisModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";
import { getData } from "./data";
import clone from "clone";

ModuleRegistry.registerModules([
  AreaSeriesModule,
  CategoryAxisModule,
  LegendModule,
  NumberAxisModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgCartesianChartOptions>({
    title: {
      text: "Sales by Month",
    },
    data: getData(),
    series: [
      {
        type: "area",
        xKey: "month",
        yKey: "subscriptions",
        yName: "Subscriptions",
        fillOpacity: 1,
        strokeWidth: 4,
      },
      {
        type: "area",
        xKey: "month",
        yKey: "services",
        yName: "Services",
        fillOpacity: 1,
        strokeWidth: 4,
      },
      {
        type: "area",
        xKey: "month",
        yKey: "products",
        yName: "Products",
        fillOpacity: 1,
        strokeWidth: 4,
      },
    ],
  });

  const enableBringToFront = () => {
    const nextOptions = clone(options);

    nextOptions.series!.forEach((series) => {
      (series as AgAreaSeriesOptions).highlight = { bringToFront: true };
    });

    setOptions(nextOptions);
  };

  const disableBringToFront = () => {
    const nextOptions = clone(options);

    nextOptions.series!.forEach((series) => {
      (series as AgAreaSeriesOptions).highlight = { bringToFront: false };
    });

    setOptions(nextOptions);
  };

  return (
    <Fragment>
      <div className="example-controls">
        <div className="controls-row">
          <button onClick={enableBringToFront}>Enable Bring to Front</button>
          <button onClick={disableBringToFront}>Disable Bring to Front</button>
        </div>
      </div>
      <AgCharts options={options} />
    </Fragment>
  );
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);
```

[Live example: Bring to Front](https://www.ag-grid.com/charts/reactFunctionalTs/series-highlighting/examples/bring-to-front)

The `bringToFront` property is enabled by default, and can be disabled in the `highlight` options if the default rendering order should be preserved.

```js
{
    highlight: {
        bringToFront: false,
    },
}
```

In the above example:

- By default, hovering any series in the chart or legend will render it above all the other series.
- This behaviour can be toggled using the buttons to see the difference when `bringToFront` is disabled.

## Customisation

The highlight styles of each series can be customised with the `highlight` options.

#### Area Series with Custom Highlight Style

```tsx
import React, { useState } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgChartOptions,
  AreaSeriesModule,
  CategoryAxisModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";

var data = [
  { quarter: "Q1", coffee: 450, tea: 270, milk: 180 },
  { quarter: "Q2", coffee: 560, tea: 380, milk: 170 },
  { quarter: "Q3", coffee: 600, tea: 450, milk: 190 },
  { quarter: "Q4", coffee: 700, tea: 520, milk: 200 },
];
ModuleRegistry.registerModules([
  AreaSeriesModule,
  CategoryAxisModule,
  LegendModule,
  NumberAxisModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgChartOptions>({
    data: data,

    theme: {
      overrides: {
        area: {
          series: {
            highlight: {
              highlightedItem: {
                fill: "yellow",
                stroke: "gold",
                strokeWidth: 2,
              },
              unhighlightedItem: {
                fill: "maroon",
                strokeWidth: 0,
              },
              highlightedSeries: {
                fill: "red",
                stroke: "maroon",
                strokeWidth: 2,
              },
              unhighlightedSeries: {
                opacity: 0.2,
              },
            },
          },
        },
      },
    },
    title: {
      text: "Beverage Expenses",
    },
    subtitle: {
      text: "per quarter",
    },
    footnote: {
      text: "Based on a sample size of 200 respondents",
    },
    series: [
      {
        type: "area",
        xKey: "quarter",
        yKey: "coffee",
        yName: "Coffee",
        marker: { enabled: true, size: 10 },
        stacked: true,
      },
      {
        type: "area",
        xKey: "quarter",
        yKey: "tea",
        yName: "Tea",
        marker: { enabled: true, size: 10 },
        stacked: true,
      },
      {
        type: "area",
        xKey: "quarter",
        yKey: "milk",
        yName: "Milk",
        marker: { enabled: true, size: 10 },
        stacked: true,
      },
    ],
  });

  return <AgCharts options={options} />;
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);
```

[Live example: Area Series with Custom Highlight Style](https://www.ag-grid.com/charts/reactFunctionalTs/series-highlighting/examples/basic-area)

```js
{
    highlight: {
        // Attributes that apply to the currently highlighted item.
        highlightedItem: {
            fill: 'yellow',
            stroke: 'gold',
            strokeWidth: 2,
        },
        // Attributes that apply to the unhighlighted items within the highlighted series.
        unhighlightedItem: {
            fill: 'maroon',
            strokeWidth: 0,
        },
        // Attributes that apply to the entire series containing the highlighted item.
        highlightedSeries: {
            fill: 'red',
            stroke: 'maroon',
            strokeWidth: 2,
        },
        // Attributes that apply to all other series.
        unhighlightedSeries: {
            opacity: 0.2,
        },
    },
}
```

In this example:

- The hovered marker is highlighted using the `highlightedItem` configuration. This changes the `fill` to `yellow`, the `stroke` to `gold`, and the `strokeWidth` to `2`.
- The non-hovered markers within the hovered series are styled using the `unhighlightedItem` configuration. This changes the `fill` to `maroon`, and removes the stroke by setting the `strokeWidth` to `0`.
- The hovered series is highlighted using the `highlightedSeries` configuration. This changes the `fill` and `stroke` to shades of red, with a `strokeWidth` of `2`.
- The non-highlighted series are dimmed with an applied opacity of `0.2` using the `unhighlightedSeries` configuration.

In the above example we provided the same `highlight` for all of the series, but the style can be unique to each series.

For simplicity, we provided the `highlight` once within a chart [Theme](https://www.ag-grid.com/charts/react/themes/), rather than repeating it on each series.

## Stylers

All [Styler](https://www.ag-grid.com/charts/react/stylers/) callbacks receive a `param.highlightState` property which can be used to dynamically customise the chart style based on the highlighted state.

#### Dynamic Highlight

```tsx
import React, { useState } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgCartesianChartOptions,
  AgChartLabelStylerParams,
  CategoryAxisModule,
  LegendModule,
  LineSeriesModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";
import { getData } from "./data";

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

const ChartExample = () => {
  const [options, setOptions] = useState<AgCartesianChartOptions>({
    title: { text: "Company Financials (Balance Sheet Overview)" },
    data: getData(),
    theme: {
      overrides: {
        line: {
          series: {
            highlight: { unhighlightedSeries: { opacity: 0.2 } },
            label: {
              enabled: true,
              itemStyler: (
                params: AgChartLabelStylerParams<unknown, unknown>,
              ) => {
                switch (params.highlightState) {
                  case "highlighted-series":
                    return { fontSize: 10 };
                  case "unhighlighted-item":
                    return { color: "lightgray" };
                  case "highlighted-item":
                    return { fontWeight: "bold" };
                  default:
                    return { color: "transparent" };
                }
              },
            },
          },
        },
      },
    },
    series: [
      {
        type: "line",
        xKey: "year",
        yKey: "cash",
        yName: "Cash",
      },
      {
        type: "line",
        xKey: "year",
        yKey: "networth",
        yName: "Net Worth",
      },
      {
        type: "line",
        xKey: "year",
        yKey: "assets",
        yName: "Assets",
      },
      {
        type: "line",
        xKey: "year",
        yKey: "liabilities",
        yName: "Liabilities",
      },
    ],
    axes: {
      x: { type: "category", title: { text: "Year" } },
      y: { type: "number", title: { text: "£ (Millions)" } },
    },
    tooltip: {
      enabled: false,
    },
    legend: {
      position: "right",
    },
  });

  return <AgCharts options={options} />;
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);
```

[Live example: Dynamic Highlight](https://www.ag-grid.com/charts/reactFunctionalTs/series-highlighting/examples/balance-sheet)

```js
{
    label: {
        itemStyler: (params) => {
            switch (params.highlightState) {
                case 'highlighted-series':
                    return { fontSize: 10 };
                case 'unhighlighted-item':
                    return { color: 'lightgray' };
                case 'highlighted-item':
                    return { fontWeight: 'bold' };
                default:
                    return { color: 'transparent' };
            }
        },
    },
}
```

In this example:

- The labels are hidden and only shown for the highlighted series.
- The label of the currently highlighted item is rendered in bold.

The `highlightState` parameter can have the following values:

- `'highlighted-item'`: The specific item is highlighted
- `'unhighlighted-item'`: Another item is highlighted, but not this one
- `'highlighted-series'`: The series containing this item is highlighted
- `'unhighlighted-series'`: Another series is highlighted, but not this one
- `'none'`: No highlighting is currently active

## API Reference

The available options differ between series types. See [the Options API](https://www.ag-grid.com/charts/options/#reference-AgChartOptions-series) for more details.