---
title: "Annotations"
enterprise: true
framework: react
version: "14.1.0"
---

# Annotations

To improve data analysis, a range of annotations can be added to Cartesian charts. These annotations are especially useful for highlighting trends and key data points.

#### Annotations

```tsx
import React, { useState } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgChartOptions,
  AnimationModule,
  AnnotationsModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

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

const ChartExample = () => {
  const [options, setOptions] = useState<AgChartOptions>({
    data: getData(),
    title: {
      text: "Monthly Sales Revenue",
    },
    footnote: {
      text: "2024, values in $1000s",
    },
    series: [
      {
        type: "line",
        xKey: "month",
        yKey: "revenue",
        interpolation: { type: "smooth" },
        marker: {
          enabled: false,
        },
        label: {
          enabled: true,
        },
      },
    ],
    annotations: {
      enabled: true,
    },
    initialState: {
      annotations: [
        {
          type: "comment",
          x: { value: "May", groupPercentage: 0.2 },
          y: 98,
          text: "Sales increased\nsignificantly\nin May",
          fontSize: 12,
        },
        {
          type: "vertical-line",
          value: "May",
          lineStyle: "dotted",
        },
        {
          type: "vertical-line",
          value: "Sep",
          lineStyle: "dotted",
        },
        {
          type: "callout",
          start: {
            x: { value: "Sep", groupPercentage: 0.1 },
            y: 80,
          },
          end: {
            x: { value: "Sep", groupPercentage: 0.5 },
            y: 55,
          },
          text: "End of summer\ndip recovered",
          fontSize: 12,
        },
        {
          type: "horizontal-line",
          value: 72,
          axisLabel: {
            fillOpacity: 0.5,
          },
          lineStyle: "dotted",
        },
        {
          type: "line",
          start: { x: "Jan", y: 32 },
          end: { x: "Dec", y: 105 },
        },
        {
          type: "parallel-channel",
          height: 13,
          start: {
            x: {
              value: "Mar",
              groupPercentage: 0.08,
            },
            y: 44.7,
          },
          end: {
            x: {
              value: "Jun",
              groupPercentage: -0.08,
            },
            y: 86.2,
          },
          strokeOpacity: 0,
        },
        {
          type: "parallel-channel",
          height: 13,
          start: {
            x: {
              value: "Aug",
              groupPercentage: 0.08,
            },
            y: 78.7,
          },
          end: {
            x: {
              value: "Oct",
              groupPercentage: -0.08,
            },
            y: 101.5,
          },
          strokeOpacity: 0,
        },
      ],
    },
  });

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

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

[Live example: Annotations](https://www.ag-grid.com/charts/reactFunctionalTs/annotations/examples/simple-annotations)

In the example above:

- Select annotations from the toolbar and click on the series area to add them.
- Use the floating options toolbar to adjust the position, colour, or style.
- Add labels or extend lines using the options available from the 'Settings' button.
- Delete annotations via the main toolbar (to delete all), or the floating toolbar (to delete individually).

## Annotation Types

A subset of annotation types is available across all Cartesian charts, including:

- **[Text Annotations](https://www.ag-grid.com/charts/react/financial-charts-toolbar/#annotations)**: `text`, `comment`, `callout` and `note`.
- **[Lines](https://www.ag-grid.com/charts/react/financial-charts-toolbar/#lines)**: `line`, `horizontal-line` and `vertical-line`.  
  For charts with a vertical [Number Axes](https://www.ag-grid.com/charts/react/axes-types/#number), the `parallel-channel` and `disjoint-channel` are also available.
- **[Arrows](https://www.ag-grid.com/charts/react/financial-charts-toolbar/#arrows)**: `arrow`, `arrow-up` and `arrow-down`.

For more details about these, and for the full set of annotations, see [Financial Charts](https://www.ag-grid.com/charts/react/financial-charts-toolbar/).

## Toolbar

The Annotations Toolbar offers menu options for annotating charts and is enabled by default. Use `toolbar.enabled: false` to disable.

The menu items in the toolbar can be customised by configuring the `toolbar.buttons` options array.

#### Annotations Toolbar

```tsx
import React, { useState } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgChartOptions,
  AnimationModule,
  AnnotationsModule,
  CategoryAxisModule,
  ChartToolbarModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

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

const ChartExample = () => {
  const [options, setOptions] = useState<AgChartOptions>({
    data: getData(),
    title: {
      text: "Monthly Sales Revenue",
    },
    footnote: {
      text: "2024, values in $1000s",
    },
    series: [
      {
        type: "line",
        xKey: "month",
        yKey: "revenue",
        interpolation: { type: "smooth" },
        marker: {
          enabled: false,
        },
      },
    ],
    annotations: {
      enabled: true,
      toolbar: {
        buttons: [
          {
            icon: "delete",
            value: "clear",
          },
          {
            icon: "text-annotation",
            value: "text-menu",
          },
        ],
      },
    },
    initialState: {
      annotations: [
        {
          type: "comment",
          x: { value: "Feb", groupPercentage: -0.2 },
          y: 46,
          text: "$45,000",
          fontSize: 12,
        },
        {
          type: "text",
          x: { value: "Jun", groupPercentage: -0.2 },
          y: 81,
          text: "$80,000",
          fontSize: 12,
        },
        {
          type: "note",
          x: "Sep",
          y: 75,
          text: "End of summer dip recovered",
          fontSize: 12,
        },
        {
          type: "callout",
          start: { x: { value: "Dec", groupPercentage: -0.1 }, y: 107 },
          end: { x: "Oct", y: 110 },
          text: "$95,000",
          fontSize: 12,
        },
      ],
    },
  });

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

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

[Live example: Annotations Toolbar](https://www.ag-grid.com/charts/reactFunctionalTs/annotations/examples/annotations-toolbar)

```js
{
    annotations: {
        enabled: true,
        toolbar: {
            buttons: [
                {
                    icon: 'delete',
                    value: 'clear',
                },
                {
                    icon: 'text-annotation',
                    value: 'text-menu',
                },
            ],
        },
    },
}
```

In the above example:

- Only the Text Annotations and Delete button are available.
- The order of these is switched.

## Keyboard Shortcuts

The following keyboard shortcuts can be used.

- `^ Ctrl`+`Z` will undo any drawing and annotation actions.
- `^ Ctrl`+`Y` will redo any undo actions.
- `^ Ctrl`+`C` will copy the selected drawing or annotation.
- `^ Ctrl`+`V` will paste the copied drawing or annotation.
- `Delete` or `⌫ Backspace` will delete the selected item.
- Arrow keys (`←` `↑` `→` `↓`) will move the selected drawing or annotation by 1 pixel.  
  Use in combination with `^ Ctrl` or `⇧ Shift` to move by 10 pixels.
- Holding down `⇧ Shift` whilst creating a drawing or dragging a handle will snap it to the nearest 45° angle.

## Save & Restore

Drawings and Annotations can be saved, restored and programmatically initialised and modified, using the [Chart State API](https://www.ag-grid.com/charts/react/api-state/).

## Read Only

Drawings and annotations can be made read only by setting the `readOnly` property to `true` for the relevant items in the `annotations` array using the [Chart State API](https://www.ag-grid.com/charts/react/api-state/). This prevents end users from selecting, editing, or deleting those annotations.

## Customisation

#### Annotation Customisation

```tsx
import React, { useState } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgChartOptions,
  AnimationModule,
  AnnotationsModule,
  CandlestickSeriesModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
  OrdinalTimeAxisModule,
  ZoomModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  AnnotationsModule,
  CandlestickSeriesModule,
  CrosshairModule,
  LegendModule,
  NumberAxisModule,
  OrdinalTimeAxisModule,
  ZoomModule,
  ContextMenuModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgChartOptions>({
    data: getData(),
    title: {
      text: "Customisation",
    },
    subtitle: {
      text: "Annotations will be initially created using a customised theme",
    },
    zoom: {},
    annotations: {
      enabled: true,
    },
    series: [
      {
        type: "candlestick",
        xKey: "date",
        openKey: "open",
        closeKey: "close",
        highKey: "high",
        lowKey: "low",
      },
    ],
    axes: {
      y: {
        type: "number",
        nice: false,
      },
    },
    theme: {
      overrides: {
        common: {
          annotations: {
            line: {
              stroke: "lime",
              strokeWidth: 3,
              lineDash: [3, 4],
            },
            "parallel-channel": {
              stroke: "red",
              strokeWidth: 4,
              background: {
                fill: "red",
              },
              middle: {
                strokeOpacity: 0,
              },
            },
            comment: {
              fill: "orange",
              color: "blue",
              stroke: "blue",
              strokeWidth: 2,
            },
          },
        },
      },
    },
    initialState: {
      annotations: [
        {
          type: "parallel-channel",
          height: 83.55795148247944,
          start: {
            x: {
              __type: "date",
              value: "Tue Sep 19 2023 00:00:00 GMT+0100 (British Summer Time)",
            },
            y: 4401.88679245283,
          },
          end: {
            x: {
              __type: "date",
              value: "Thu Oct 05 2023 00:00:00 GMT+0100 (British Summer Time)",
            },
            y: 4279.245283018868,
          },
        },
        {
          type: "line",
          start: {
            x: {
              __type: "date",
              value: "Tue Sep 05 2023 00:00:00 GMT+0100 (British Summer Time)",
            },
            y: 4507.681940700809,
          },
          end: {
            x: {
              __type: "date",
              value: "Fri Oct 13 2023 00:00:00 GMT+0100 (British Summer Time)",
            },
            y: 4331.805929919137,
          },
        },
        {
          type: "comment",
          text: "Comment",
          visible: true,
          x: {
            __type: "date",
            value: "Tue Aug 22 2023 00:00:00 GMT+0100 (British Summer Time)",
          },
          y: 4261.725067385445,
        },
      ],
    },
  });

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

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

[Live example: Annotation Customisation](https://www.ag-grid.com/charts/reactFunctionalTs/annotations/examples/annotations-customisation)

To customise the initial look of Drawings and Annotations, use [Theme Override Options](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-common-annotations).

```js
{
    theme: {
        overrides: {
            common: {
                annotations: {
                    line: {
                        stroke: 'lime',
                        strokeWidth: 3,
                        lineDash: [3, 4],
                    },
                    'parallel-channel': {
                        stroke: 'red',
                        strokeWidth: 4,
                        background: {
                            fill: 'red',
                        },
                        middle: {
                            strokeOpacity: 0,
                        },
                    },
                    comment: {
                        fill: 'orange',
                        color: 'blue',
                        stroke: 'blue',
                        strokeWidth: 2,
                    },
                },
            },
        },
    },
}
```

## API Reference

#### Annotation Options

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| axesButtons | AgAnnotationAxesButtons |  | The options for the axes buttons |
| axesButtons.axes | 'x' \| 'y' \| 'xy' |  | Which axis should display the annotation buttons. |
| axesButtons.enabled | boolean |  | Whether the associated elements and properties should be used in the chart. |
| toolbar | AgAnnotationsToolbar |  | Configuration for the toolbar for creating annotations. |
| toolbar.buttons | AgAnnotationsToolbarButton[] |  | The buttons to show in the toolbar. |
| toolbar.buttons.value (required) | AgAnnotationsToolbarButtonValue |  | The action to perform when the button is clicked. |
| toolbar.buttons.icon | AgIconName |  | Icon to display on the button. |
| toolbar.buttons.iconPosition | 'before' \| 'after' | 'before' | Position of the icon, before or after the label. |
| toolbar.buttons.label | string |  | Text label to display on the button. |
| toolbar.buttons.ariaLabel | string |  | Text label to announce in screen readers. |
| toolbar.buttons.tooltip | string |  | Tooltip text to display on hover over the button. |
| toolbar.padding | number |  | Padding in pixels around the toolbar. |
| toolbar.enabled | boolean |  | Whether the associated elements and properties should be used in the chart. |
| optionsToolbar | AgAnnotationOptionsToolbar |  | Configuration for the options toolbar for editing an annotation. |
| optionsToolbar.buttons | Array<AgAnnotationOptionsToolbarButton \| AgAnnotationOptionsToolbarSwitch> |  | The buttons to show in the options toolbar. |
| optionsToolbar.enabled | boolean |  | Whether the associated elements and properties should be used in the chart. |
| enabled | boolean |  | Whether the associated elements and properties should be used in the chart. |