---
title: "Annotations"
enterprise: true
framework: javascript
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

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

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

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

[Live example: Annotations](https://www.ag-grid.com/charts/typescript/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/javascript/financial-charts-toolbar/#annotations)**: `text`, `comment`, `callout` and `note`.
- **[Lines](https://www.ag-grid.com/charts/javascript/financial-charts-toolbar/#lines)**: `line`, `horizontal-line` and `vertical-line`.  
  For charts with a vertical [Number Axes](https://www.ag-grid.com/charts/javascript/axes-types/#number), the `parallel-channel` and `disjoint-channel` are also available.
- **[Arrows](https://www.ag-grid.com/charts/javascript/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/javascript/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

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

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

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

[Live example: Annotations Toolbar](https://www.ag-grid.com/charts/typescript/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/javascript/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/javascript/api-state/). This prevents end users from selecting, editing, or deleting those annotations.

## Customisation

#### Annotation Customisation

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

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

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

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