SciChart.js JavaScript 2D Charts API > Annotations API > The Annotations API Overview
The Annotations API Overview

SciChart.js features a rich Annotations API, that allows you to place annotations (boxes, markers, text labels and custom shapes) over a chart:

JavaScript Chart Annotations by SciChart.js

Annotations can provide interactive event/news bullets, horizontal/vertical lines (thresholds), text/callouts as well as measurements such as Peak-to-peak or cycle duration. Annotations can be edited by click & drag, added by touching a screen, or, simply created programmatically. SciChart provides a number of built-in annotations, but you can also create your own. To find out more about annotations features, please see the Common Annotations Features article.

Annotation Types

The following annotation types are available out of the box in SciChart:

Type Description
BoxAnnotation Draws a rectangle at specific X1, X2, Y1, Y2 coordinates.
LineAnnotation Draws a line between X1, Y1 and X2, Y2 positions.
TextAnnotation Allows to place a piece of text at a specific location on a chart.
CustomAnnotation Allows to place any SVG Content at a specific location on a chart.


To learn more about any annotation type, please refer to the corresponding article.

Adding an Annotation to a Chart

The SciChartSurface stores all its annotations in the SciChartSurface.annotations collection. The following code can be used to add an annotation to a chart:

Copy Code
import {BoxAnnotation} from "../../../../../../../src/Charting/Visuals/Annotations/BoxAnnotation";
import {CustomAnnotation} from "../../../../../../../src/Charting/Visuals/Annotations/CustomAnnotation";
import {LineAnnotation} from "../../../../../../../src/Charting/Visuals/Annotations/LineAnnotation";
import {TextAnnotation} from "../../../../../../../src/Charting/Visuals/Annotations/TextAnnotation";
import {NumericAxis} from "../../../../../../../src/Charting/Visuals/Axis/NumericAxis";
import {SciChartSurface} from "../../../../../../../src/Charting/Visuals/SciChartSurface";
import {NumberRange} from "../../../../../../../src/Core/NumberRange";
import {EHorizontalAnchorPoint, EVerticalAnchorPoint} from "../../../../../../../src/types/AnchorPoint";
import {ECoordinateMode} from "../../../../../../../src/Charting/Visuals/Annotations/AnnotationBase";

const { sciChartSurface, wasmContext } = await SciChartSurface.create(divElementId);
const xAxis = new NumericAxis(wasmContext);
xAxis.visibleRange = new NumberRange(0, 10);
const yAxis = new NumericAxis(wasmContext);
yAxis.visibleRange = new NumberRange(0, 10);
    new LineAnnotation({ stroke: "#FF6600", strokeThickness: 3, x1: 2.0, x2: 8.0, y1: 3.0, y2: 7.0 }),
    new BoxAnnotation({
        stroke: "#FF3333",
        strokeThickness: 1,
        fill: "rgba(255,50,50,0.3)",
        x1: 2.0,
        x2: 8.0,
        y1: 3.0,
        y2: 7.0
    new BoxAnnotation({
        stroke: "#33FF33",
        strokeThickness: 1,
        fill: "rgba(50, 255, 50, 0.3)",
        x1: 3.0,
        x2: 9.0,
        y1: 4.0,
        y2: 8.0
    new TextAnnotation({
        x1: 100,
        y1: 0.5,
        xCoordinateMode: ECoordinateMode.Pixel,
        yCoordinateMode: ECoordinateMode.Relative,
        horizontalAnchorPoint: EHorizontalAnchorPoint.Left,
        verticalAnchorPoint: EVerticalAnchorPoint.Center,
        textColor: "yellow",
        fontSize: 26,
        fontFamily: "Times New Roman",
        text: "TEXT ANNOTATION",

Individual Annotation features are discussed in greater detail in the following pages:

Common Annotation Properties

All annotations in SciChart.js are derived from the AnnotationBase type. Individual Annotations have additional properties however the following common properties of the AnnotationBase class listed below can be used to control all annotation types.

AnnotationBase Property Description

Determines which canvas the annotation should be placed on.

The default is EAnnotationLayer.AboveChart, where annotations are displayed above the chart series.

Setting this property to EAnnotationLayer.BelowChart places an annotation below series and gridlines, and is useful for watermarks.          


Determines how coordinates x1,y2,x2,y2 are used when placing the annotation. X/YCoordinateMode should be used to place watermarks, or annotations anchored to the top or bottom of the viewport etc…


The default is ECoordinateMode.DataValue. In this mode, x1,y2,x2,y2 correspond to Data-values and the annotion position will update as you zoom and pan the chart.

ECoordinateMode.Relative means that coordinates are relative to the viewport. The annotation does not update position as you zoom and pan. E.g. x1=0.0 and y1=0.0 means the annotation will be placed in the top-left corner of the Viewport and x1=1.0, y1=1.0 corresponds to the bottom-left corner of the viewport always (regardless of Zoom or Pan).

ECoordinateMode.Pixel means that coordinates are pixel values relative to the top-left of the viewport. These are also useful to dock annotations to a specific


The horizontalAnchorPoint, verticalAnchorPoint properties are used to adjust the alignment of certain annotations.

Above: HorizontalAnchorPoint, VerticalAnchorPoint when applied to a TextAnnotation

isHidden isHidden can be set to show or hide an annotation.

x1,x2,y1,y2 properties are set to define the position of the annotation on the parent chart.

Note that annotation position is also defined by the xCoordinateMode, yCoordinateMode properties, which allow you to place annotations using data-values, relative to the viewport or absolute pixel coordinates.


In a multiple-axis scenario, AnnotationBase.xAxisId or yAxisId property is used to bind the annotation to a specific X or Y-Axis.

NOTE: This value must be supplied if you have axis with non-default Axis Ids.



See Also