JavaScript ChartsAnnotations

Version 14.2.0

Enterprise

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.

main.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);

data.ts

export function getData() {
  return [
    { month: "Jan", revenue: 32 },
    { month: "Feb", revenue: 45 },
    { month: "Mar", revenue: 38 },
    { month: "Apr", revenue: 50 },
    { month: "May", revenue: 65 },
    { month: "Jun", revenue: 80 },
    { month: "Jul", revenue: 78 },
    { month: "Aug", revenue: 72 },
    { month: "Sep", revenue: 85 },
    { month: "Oct", revenue: 95 },
    { month: "Nov", revenue: 90 },
    { month: "Dec", revenue: 105 },
  ];
}

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 Copy Link

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

Text Annotations: text, comment, callout and note.
Lines: line, horizontal-line and vertical-line.
For charts with a vertical Number Axes, the parallel-channel and disjoint-channel are also available.
Arrows: arrow, arrow-up and arrow-down.

For more details about these, and for the full set of annotations, see Financial Charts.

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.

main.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);

data.ts

export function getData() {
  return [
    { month: "Jan", revenue: 32 },
    { month: "Feb", revenue: 45 },
    { month: "Mar", revenue: 38 },
    { month: "Apr", revenue: 50 },
    { month: "May", revenue: 65 },
    { month: "Jun", revenue: 80 },
    { month: "Jul", revenue: 78 },
    { month: "Aug", revenue: 72 },
    { month: "Sep", revenue: 85 },
    { month: "Oct", revenue: 95 },
    { month: "Nov", revenue: 90 },
    { month: "Dec", revenue: 105 },
  ];
}

{
    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 Copy Link

The following keyboard shortcuts can be used.

^ Ctrl⌘ Command+Z will undo any drawing and annotation actions.
^ Ctrl⌘ Command+Y will redo any undo actions.
^ Ctrl⌘ Command+C will copy the selected drawing or annotation.
^ Ctrl⌘ Command+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⌘ Command 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 Copy Link

Drawings and Annotations can be saved, restored and programmatically initialised and modified, using the Chart State API.

Read Only Copy Link

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. This prevents end users from selecting, editing, or deleting those annotations.

Customisation Copy Link

main.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);

data.ts

export function getData() {
  return [
    {
      date: new Date("Wednesday, August 02, 2023"),
      open: 4550.93,
      high: 4550.93,
      low: 4505.75,
      close: 4513.39,
    },
    {
      date: new Date("Thursday, August 03, 2023"),
      open: 4494.27,
      high: 4519.49,
      low: 4485.54,
      close: 4501.89,
    },
    {
      date: new Date("Friday, August 04, 2023"),
      open: 4513.96,
      high: 4540.34,
      low: 4474.55,
      close: 4478.03,
    },
    {
      date: new Date("Monday, August 07, 2023"),
      open: 4491.58,
      high: 4519.84,
      low: 4491.15,
      close: 4518.44,
    },
    {
      date: new Date("Tuesday, August 08, 2023"),
      open: 4498.03,
      high: 4503.31,
      low: 4464.39,
      close: 4499.38,
    },
    {
      date: new Date("Wednesday, August 09, 2023"),
      open: 4501.57,
      high: 4502.44,
      low: 4461.33,
      close: 4467.71,
    },
    {
      date: new Date("Thursday, August 10, 2023"),
      open: 4487.16,
      high: 4527.37,
      low: 4457.92,
      close: 4468.83,
    },
    {
      date: new Date("Friday, August 11, 2023"),
      open: 4450.69,
      high: 4476.23,
      low: 4443.98,
      close: 4464.05,
    },
    {
      date: new Date("Monday, August 14, 2023"),
      open: 4458.13,
      high: 4490.33,
      low: 4453.44,
      close: 4489.72,
    },
    {
      date: new Date("Tuesday, August 15, 2023"),
      open: 4478.87,
      high: 4478.87,
      low: 4432.19,
      close: 4437.86,
    },
    {
      date: new Date("Wednesday, August 16, 2023"),
      open: 4433.79,
      high: 4449.95,
      low: 4403.55,
      close: 4404.33,
    },
    {
      date: new Date("Thursday, August 17, 2023"),
      open: 4416.32,
      high: 4421.17,
      low: 4364.83,
      close: 4370.36,
    },
    {
      date: new Date("Friday, August 18, 2023"),
      open: 4344.88,
      high: 4381.82,
      low: 4335.31,
      close: 4369.71,
    },
    {
      date: new Date("Monday, August 21, 2023"),
      open: 4380.28,
      high: 4407.55,
      low: 4360.3,
      close: 4399.77,
    },
    {
      date: new Date("Tuesday, August 22, 2023"),
      open: 4415.33,
      high: 4418.59,
      low: 4382.77,
      close: 4387.55,
    },
    {
      date: new Date("Wednesday, August 23, 2023"),
      open: 4396.44,
      high: 4443.18,
      low: 4396.44,
      close: 4436.01,
    },
    {
      date: new Date("Thursday, August 24, 2023"),
      open: 4455.16,
      high: 4458.3,
      low: 4375.55,
      close: 4376.31,
    },
    {
      date: new Date("Friday, August 25, 2023"),
      open: 4389.38,
      high: 4418.46,
      low: 4356.29,
      close: 4405.71,
    },

    {
      date: new Date("Monday, August 28, 2023"),
      open: 4426.03,
      high: 4439.56,
      low: 4414.98,
      close: 4433.31,
    },
    {
      date: new Date("Tuesday, August 29, 2023"),
      open: 4432.75,
      high: 4500.14,
      low: 4431.68,
      close: 4497.63,
    },
    {
      date: new Date("Wednesday, August 30, 2023"),
      open: 4500.34,
      high: 4521.65,
      low: 4493.59,
      close: 4514.87,
    },

    {
      date: new Date("Thursday, August 31, 2023"),
      open: 4517.01,
      high: 4532.26,
      low: 4507.39,
      close: 4507.66,
    },

    {
      date: new Date("Friday, September 01, 2023"),
      open: 4530.6,
      high: 4541.25,
      low: 4501.35,
      close: 4515.77,
    },
    {
      date: new Date("Tuesday, September 05, 2023"),
      open: 4510.06,
      high: 4514.29,
      low: 4496.01,
      close: 4496.83,
    },
    {
      date: new Date("Wednesday, September 06, 2023"),
      open: 4490.35,
      high: 4490.35,
      low: 4442.38,
      close: 4465.48,
    },
    {
      date: new Date("Thursday, September 07, 2023"),
      open: 4434.55,
      high: 4457.81,
      low: 4430.46,
      close: 4451.14,
    },
    {
      date: new Date("Friday, September 08, 2023"),
      open: 4451.3,
      high: 4473.53,
      low: 4448.38,
      close: 4457.49,
    },
    {
      date: new Date("Monday, September 11, 2023"),
      open: 4480.98,
      high: 4490.77,
      low: 4467.89,
      close: 4487.46,
    },
    {
      date: new Date("Tuesday, September 12, 2023"),
      open: 4473.27,
      high: 4487.11,
      low: 4456.83,
      close: 4461.9,
    },
    {
      date: new Date("Wednesday, September 13, 2023"),
      open: 4462.65,
      high: 4479.39,
      low: 4453.52,
      close: 4467.44,
    },
    {
      date: new Date("Thursday, September 14, 2023"),
      open: 4487.78,
      high: 4511.99,
      low: 4478.69,
      close: 4505.1,
    },
    {
      date: new Date("Friday, September 15, 2023"),
      open: 4497.98,
      high: 4497.98,
      low: 4447.21,
      close: 4450.32,
    },
    {
      date: new Date("Monday, September 18, 2023"),
      open: 4445.13,
      high: 4466.36,
      low: 4442.11,
      close: 4453.53,
    },
    {
      date: new Date("Tuesday, September 19, 2023"),
      open: 4445.41,
      high: 4449.85,
      low: 4416.61,
      close: 4443.95,
    },
    {
      date: new Date("Wednesday, September 20, 2023"),
      open: 4452.81,
      high: 4461.03,
      low: 4401.38,
      close: 4402.2,
    },

    {
      date: new Date("Thursday, September 21, 2023"),
      open: 4374.36,
      high: 4375.7,
      low: 4329.17,
      close: 4330.0,
    },
    {
      date: new Date("Friday, September 22, 2023"),
      open: 4341.74,
      high: 4357.4,
      low: 4316.49,
      close: 4320.06,
    },
    {
      date: new Date("Monday, September 25, 2023"),
      open: 4310.62,
      high: 4338.51,
      low: 4302.7,
      close: 4337.44,
    },
    {
      date: new Date("Tuesday, September 26, 2023"),
      open: 4312.88,
      high: 4313.01,
      low: 4265.98,
      close: 4273.53,
    },
    {
      date: new Date("Wednesday, September 27, 2023"),
      open: 4282.63,
      high: 4292.07,
      low: 4238.63,
      close: 4274.51,
    },
    {
      date: new Date("Thursday, September 28, 2023"),
      open: 4269.65,
      high: 4317.27,
      low: 4264.38,
      close: 4299.7,
    },
    {
      date: new Date("Friday, September 29, 2023"),
      open: 4328.18,
      high: 4333.15,
      low: 4274.86,
      close: 4288.05,
    },
    {
      date: new Date("Monday, October 02, 2023"),
      open: 4284.52,
      high: 4300.58,
      low: 4260.21,
      close: 4288.39,
    },
    {
      date: new Date("Tuesday, October 03, 2023"),
      open: 4269.75,
      high: 4281.15,
      low: 4216.45,
      close: 4229.45,
    },
    {
      date: new Date("Wednesday, October 04, 2023"),
      open: 4233.83,
      high: 4268.5,
      low: 4220.48,
      close: 4263.75,
    },
    {
      date: new Date("Thursday, October 05, 2023"),
      open: 4259.31,
      high: 4267.13,
      low: 4225.91,
      close: 4258.19,
    },
    {
      date: new Date("Friday, October 06, 2023"),
      open: 4234.79,
      high: 4324.1,
      low: 4219.55,
      close: 4308.5,
    },
    {
      date: new Date("Monday, October 09, 2023"),
      open: 4289.02,
      high: 4341.73,
      low: 4283.79,
      close: 4335.66,
    },
    {
      date: new Date("Tuesday, October 10, 2023"),
      open: 4339.75,
      high: 4385.46,
      low: 4339.64,
      close: 4358.24,
    },
    {
      date: new Date("Wednesday, October 11, 2023"),
      open: 4366.59,
      high: 4378.64,
      low: 4345.34,
      close: 4376.95,
    },
    {
      date: new Date("Thursday, October 12, 2023"),
      open: 4380.94,
      high: 4385.85,
      low: 4325.43,
      close: 4349.61,
    },
    {
      date: new Date("Friday, October 13, 2023"),
      open: 4360.49,
      high: 4377.1,
      low: 4311.97,
      close: 4327.78,
    },
    {
      date: new Date("Monday, October 16, 2023"),
      open: 4342.37,
      high: 4383.33,
      low: 4342.37,
      close: 4373.63,
    },
    {
      date: new Date("Tuesday, October 17, 2023"),
      open: 4345.23,
      high: 4393.57,
      low: 4337.54,
      close: 4373.2,
    },
    {
      date: new Date("Wednesday, October 18, 2023"),
      open: 4357.35,
      high: 4364.2,
      low: 4303.84,
      close: 4314.6,
    },
    {
      date: new Date("Thursday, October 19, 2023"),
      open: 4321.36,
      high: 4339.54,
      low: 4269.69,
      close: 4278.0,
    },
    {
      date: new Date("Friday, October 20, 2023"),
      open: 4273.85,
      high: 4276.56,
      low: 4223.03,
      close: 4224.16,
    },
    {
      date: new Date("Monday, October 23, 2023"),
      open: 4210.4,
      high: 4255.84,
      low: 4189.22,
      close: 4217.04,
    },
    {
      date: new Date("Tuesday, October 24, 2023"),
      open: 4235.79,
      high: 4259.38,
      low: 4219.43,
      close: 4247.68,
    },
    {
      date: new Date("Wednesday, October 25, 2023"),
      open: 4232.42,
      high: 4232.42,
      low: 4181.42,
      close: 4186.77,
    },
    {
      date: new Date("Thursday, October 26, 2023"),
      open: 4175.99,
      high: 4183.6,
      low: 4127.9,
      close: 4137.23,
    },
    {
      date: new Date("Friday, October 27, 2023"),
      open: 4152.93,
      high: 4156.7,
      low: 4103.78,
      close: 4117.37,
    },
    {
      date: new Date("Monday, October 30, 2023"),
      open: 4139.39,
      high: 4177.47,
      low: 4132.94,
      close: 4166.82,
    },
    {
      date: new Date("Tuesday, October 31, 2023"),
      open: 4171.33,
      high: 4195.55,
      low: 4153.12,
      close: 4193.8,
    },
    {
      date: new Date("Wednesday, November 01, 2023"),
      open: 4201.27,
      high: 4245.64,
      low: 4197.74,
      close: 4237.86,
    },
  ];
}

To customise the initial look of Drawings and Annotations, use Theme Override Options.

{
    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 Copy Link

Properties available on the AgAnnotationsOptions interface.

axesButtons AgAnnotationAxesButtons: The options for the axes buttons
toolbar AgAnnotationsToolbar: Configuration for the toolbar for creating annotations.
optionsToolbar AgAnnotationOptionsToolbar: Configuration for the options toolbar for editing an annotation.
enabled boolean: Whether the associated elements and properties should be used in the chart.

Getting started

AI Features

Core features

Specialised Charts

Series

Gauges

JavaScript ChartsAnnotations

Annotation Types Copy Link

Keyboard Shortcuts Copy Link

Save & Restore Copy Link

Read Only Copy Link

Customisation Copy Link

API Reference Copy Link

Getting started

AI Features

Core features

Specialised Charts

Series

Gauges

Annotation Types Copy Link

Toolbar Copy Link

Keyboard Shortcuts Copy Link

Save & Restore Copy Link

Read Only Copy Link

Customisation Copy Link

API Reference Copy Link