---
title: "Series Highlighting"
framework: javascript
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

```ts
import {
  AgChartOptions,
  AgCharts,
  BarSeriesModule,
  CategoryAxisModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";
import { getData } from "./data";

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

const options: 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,
    },
  ],
};

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

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

[Live example: Simple Highlight](https://www.ag-grid.com/charts/typescript/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

```ts
import {
  AgAreaSeriesOptions,
  AgCartesianChartOptions,
  AgCharts,
  AreaSeriesModule,
  CategoryAxisModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";
import { getData } from "./data";

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

const options: 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,
    },
  ],
};

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

const chart = AgCharts.create(options);

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

  chart.update(options);
}

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

  chart.update(options);
}

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

[Live example: Bring to Front](https://www.ag-grid.com/charts/typescript/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

```ts
import {
  AgChartOptions,
  AgCharts,
  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 options: 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,
    },
  ],
};

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

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

[Live example: Area Series with Custom Highlight Style](https://www.ag-grid.com/charts/typescript/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/javascript/themes/), rather than repeating it on each series.

## Stylers

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

#### Dynamic Highlight

```ts
import {
  AgCartesianChartOptions,
  AgChartLabelStylerParams,
  AgCharts,
  CategoryAxisModule,
  LegendModule,
  LineSeriesModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";
import { getData } from "./data";

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

const options: 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",
  },
};

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

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

[Live example: Dynamic Highlight](https://www.ag-grid.com/charts/typescript/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.