---
title: "Series Highlighting"
framework: vue
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 { createApp, defineComponent, ref } from "vue";
import { AgCharts } from "ag-charts-vue3";
import type { AgChartOptions } from "ag-charts-types";
import {
  BarSeriesModule,
  CategoryAxisModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";
import { getData } from "./data";

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

const ChartExample = defineComponent({
  template: `
    <ag-charts
      :options="options"
    />
  `,
  components: {
    "ag-charts": AgCharts,
  },
  setup(props) {
    const options = ref<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 {
      options,
    };
  },
});

createApp(ChartExample).mount("#app");
```

[Live example: Simple Highlight](https://www.ag-grid.com/charts/vue3/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 { createApp, defineComponent, ref } from "vue";
import { AgCharts } from "ag-charts-vue3";
import type { AgChartOptions } from "ag-charts-types";
import {
  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 = defineComponent({
  template: `
    <div class="example-controls">
      <div class="controls-row">
        <button v-on:click="enableBringToFront()">Enable Bring to Front</button>
        <button v-on:click="disableBringToFront()">Disable Bring to Front</button>
      </div>
    </div>
    <ag-charts
      :options="options"
    />
  `,
  components: {
    "ag-charts": AgCharts,
  },
  setup(props) {
    const options = ref<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 optionsCopy = clone(options.value);

      optionsCopy.series.forEach((series) => {
        series.highlight = { bringToFront: true };
      });

      options.value = optionsCopy;
    };
    const disableBringToFront = () => {
      const optionsCopy = clone(options.value);

      optionsCopy.series.forEach((series) => {
        series.highlight = { bringToFront: false };
      });

      options.value = optionsCopy;
    };

    return {
      options,
      enableBringToFront,
      disableBringToFront,
    };
  },
});

createApp(ChartExample).mount("#app");
```

[Live example: Bring to Front](https://www.ag-grid.com/charts/vue3/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 { createApp, defineComponent, ref } from "vue";
import { AgCharts } from "ag-charts-vue3";
import type { AgChartOptions } from "ag-charts-types";
import {
  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 = defineComponent({
  template: `
    <ag-charts
      :options="options"
    />
  `,
  components: {
    "ag-charts": AgCharts,
  },
  setup(props) {
    const options = ref<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 {
      options,
    };
  },
});

createApp(ChartExample).mount("#app");
```

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

## Stylers

All [Styler](https://www.ag-grid.com/charts/vue/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 { createApp, defineComponent, ref } from "vue";
import { AgCharts } from "ag-charts-vue3";
import type { AgChartOptions } from "ag-charts-types";
import {
  CategoryAxisModule,
  LegendModule,
  LineSeriesModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";
import { getData } from "./data";

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

const ChartExample = defineComponent({
  template: `
    <ag-charts
      :options="options"
    />
  `,
  components: {
    "ag-charts": AgCharts,
  },
  setup(props) {
    const options = ref<AgCartesianChartOptions>({
      title: { text: "Company Financials (Balance Sheet Overview)" },
      data: getData(),
      theme: {
        overrides: {
          line: {
            series: {
              highlight: { unhighlightedSeries: { opacity: 0.2 } },
              label: {
                enabled: true,
                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" };
                  }
                },
              },
            },
          },
        },
      },
      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 {
      options,
    };
  },
});

createApp(ChartExample).mount("#app");
```

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