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:


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.
HorizontalLineAnnotation Draws a horizontal line at a given y position, with various labelling options
VerticalLineAnnotation Draws a vertical line at a given x position, with various labelling options
TextAnnotation Allows to place a piece of text at a specific location on a chart.
NativeTextAnnotation Draws text natively rather than using svg, supporting rotation, multiline, wordwrap and scaling

Allows to place any SVG Content at a specific location on a chart.

CustomAxisMarkerAnnotation Uses an image instead of text for an axis marker


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.

isEditable If true, this annotation can be selected and dragged/resized.  See Editable Annotations for more details
clicked / onClick

clicked is an event on the annotation which you can subscribe to to be notified when the annotation is clicked.  This is fired for both editable and non-editable annotations.  You can pass a callback for this using the onClick property of the IAnnotationBaseOptions.  The event arguments contain a point which gives the coordinates of where on the annotation it was clicked, relative to the top left corner.

NOTE:  If and editable annotation is already selected, clicking on it will fire dragStarted, but not clicked



See Also