Annotations

Annotations turn a bare series into a story — pin the moments that matter, shade the intervals, and draw the levels, all without leaking into the tooltip, legend, or Y-range.

Three ways to annotate any chart on one canvas: markers pin the moments, a region shades the window, and reference lines draw the baseline, the limit, and the deploy that set it off.

Change the marker shape, or toggle the window between ongoing and settled.

Marker shape:
405060708090
22:15:0022:30:0022:45:0023:00:0023:15:00
01 — MARKERS: PIN A MOMENT
A <Marker> pins a single moment to the chart — "deploy shipped", "peak", "released". Give it an explicit value, or a seriesId and it snaps to that series' value at time, riding the curve. shape is 'dot' | 'circle' | 'arrow-up' | 'arrow-down'; pulse reuses the live line halo; label draws a text pill.
<Marker time={peakMs} seriesId="metric" shape="arrow-down" pulse={true} label="peak" color="#f0556a" />
02 — REGIONS: SHADE AN INTERVAL
A <TimeRegion> shades a time interval with a translucent band — a session, a campaign, a window something was happening. It draws behind the series, so the data reads on top. Omit to (or pass 'now') for an open-ended band that runs to the right edge — flip ongoing above the chart to see it.
<TimeRegion from={fromMs} to={toMs ?? 'now'} fill="rgba(240,85,106,0.1)" label="window" />
03 — REFERENCE LINES: DRAW A LEVEL
A <ReferenceLine> is a straight line across the plot — a horizontal level pinned to a value (baseline, target, limit), or a vertical boundary pinned to a time (mutually exclusive). It draws above the series so a threshold reads on top of the data. style is 'solid' | 'dashed'.
// horizontal level
<ReferenceLine value={70} label="limit 70" color="#f0a83c" />
 
// vertical boundary in time
<ReferenceLine time={deployMs} label="deploy v2.1.0" color="#cba6f7" />
04 — OUT OF THE SERIES MODEL
All three are annotations, not data: excluded from the tooltip, legend, and Y-range autoscale, and they never pollute series queries. Prop sets are identical across React, Vue, and Svelte (parity-checked in CI), each with imperative core equivalents — addMarker, addRegion, addLine (plus update* / remove*) — the same methods the components call under the hood.
chart.addMarker({ time: peakMs, seriesId: 'metric', label: 'peak', pulse: true });
chart.addRegion({ from: fromMs, to: 'now', label: 'window' });
chart.addLine({ value: 70, label: 'limit 70', color: '#f0a83c' });
chart.addLine({ time: deployMs, label: 'deploy v2.1.0', color: '#cba6f7' });