Annotations
An annotation marks a level or a span that matters: a support price, a reporting window, a single candle worth calling out. They are anchored in data space, so they stay put through zoom, pan, an update(), a theme switch and a chart-type switch.
chart.addAnnotation({ type: 'yLine', y: 187.4, label: 'Resistance' })
chart.addAnnotation({ type: 'xBand', x: '2024-02-01', x2: '2024-02-15', label: 'Earnings window' })
| Method | Does |
|---|---|
addAnnotation(config) | Adds one, or replaces it if id already exists. Returns the id, or null on invalid input |
updateAnnotation(id, patch) | Patches one |
removeAnnotation(id) | Removes one |
clearAnnotations() | Removes all |
getAnnotation(id) / getAnnotations() | Reads them back, meta included |
Everything is managed by id, so removing an annotation never disturbs a trading price line or an indicator's own annotations.
Six types
| Type | Anchors on | Draws |
|---|---|---|
yLine | y | A horizontal price level |
yBand | y, y2 | A shaded price range |
xLine | x | A vertical time marker |
xBand | x, x2 | A shaded time span |
point | x, y | A marker at one coordinate |
text | x, y | A text label at one coordinate |
x takes a timestamp, a date string, or a Date.
Config
| Key | Applies to | What it is |
|---|---|---|
id | all | A stable id. Auto-generated as anno-N when omitted |
label | all | The label text. text is an alias, which reads better for type: 'text' |
color | all | Line, marker and label color. Defaults from the theme |
fillColor, opacity | bands | The fill, defaulting to color |
textColor | all | Label text color |
width, strokeDashArray | lines | Stroke width and dash length |
labelPosition | y annotations | 'left' or 'right' |
marker | point | Marker overrides, such as { size, shape, fillColor } |
meta | all | Anything of yours, returned by getAnnotation and getAnnotations |
Colors default from the active theme, so an annotation with no styling stays legible after a mode or preset switch.
Three overlay layers, and which to use
Annotations are one of three ways to put something on the chart, and they are not interchangeable:
| Annotations | Trading price lines | Drawings | |
|---|---|---|---|
| Placed by | Your code | Your code | The user, or your code |
| Draggable | No | Yes | Yes |
| Callbacks | No | onCross, onMove, onRemove | Events only |
| For | Editorial marks and reference levels | Orders, stops, targets and alerts | Technical analysis |
Use an annotation when the mark is a statement rather than a control. Reach for a price line when the reader is meant to move it or when a streamed bar crossing it should fire something.
Persistence
Annotations are captured by getState() and restored by setState(), meta included. Unlike price lines they carry no callbacks, so nothing has to be re-bound after a restore.
See also
- Event Markers for flags on the x-axis strip
- Trading Overlays for draggable lines with callbacks
- Drawing Tools for the anchored drawing layer