v0.4.0
Docs npm … Get started

Guides

Annotations

Declarative overlays on options.annotations: lineX, lineY, bandX, point, and text. Optional createAnnotationAuthoring adds right-click create/edit, drag, undo/redo, and JSON export.

Types

Each entry is an object with a type field. Set layer to 'belowSeries' or 'aboveSeries'. Use a stable id when you patch annotations from app state.

  • lineY: horizontal line at y; optional label (text or template)
  • lineX: vertical line at x; optional label
  • bandX: filled x-range via from/to (order free); no label field
  • point: marker at (x, y) with optional marker and label
  • text: string at position in data or plot space (plot is 0–1 normalized)

Interactive annotation playground

Seed layers come from the toggles below. On the chart, right-click to add a vertical/horizontal line or text note, drag existing annotations to reposition them, and right-click an annotation to edit or delete (createAnnotationAuthoring). Use Undo / Redo / Export JSON in the bar under the chart.

Recipes

Horizontal threshold

TypeScript
{
  type: 'lineY',
  y: 0.35,
  layer: 'belowSeries',
  style: { color: '#D4A520', lineWidth: 2, lineDash: [8, 6], opacity: 0.95 },
  label: { template: 'max y={y}', decimals: 2 },
}

Vertical event marker

TypeScript
{
  type: 'lineX',
  x: eventTimestamp,
  layer: 'belowSeries',
  style: { color: '#6BCB77', lineWidth: 2, opacity: 0.9 },
  label: { text: 'deploy' },
}

Highlighted region

bandX fills a vertical window. It has no label field; pair with a text annotation for captions. from/to order does not matter.

TypeScript
{
  type: 'bandX',
  from: outageStart,
  to: outageEnd,
  layer: 'belowSeries',
  style: { color: '#E05A8C', opacity: 0.14 },
},
{
  type: 'text',
  layer: 'aboveSeries',
  position: { space: 'data', x: outageStart, y: 0.9 },
  text: 'regime',
  style: { color: '#E05A8C', opacity: 0.95 },
}

Peak marker

TypeScript
{
  type: 'point',
  x: maxX,
  y: maxY,
  layer: 'aboveSeries',
  marker: { symbol: 'circle', size: 9, style: { color: '#E05A8C' } },
  label: { template: 'peak={y}', decimals: 2 },
}

Plot-space text

Use position.space: 'plot' for labels pinned in the plot (0–1 normalized). Data-space text tracks pan/zoom with the series.

TypeScript
{
  type: 'text',
  position: { space: 'plot', x: 0.04, y: 0.08 },
  text: 'note',
  layer: 'aboveSeries',
  style: { color: '#6BCB77', opacity: 0.95 },
}

Interactive authoring

createAnnotationAuthoring mounts context-menu create/edit, drag, undo/redo, and JSON export on an existing chart. Dispose the authoring helper before the chart.

TypeScript
import { ChartGPU, createAnnotationAuthoring } from '@chartgpu/chartgpu';

const chart = await ChartGPU.create(container, {
  series: [{ type: 'line', data }],
  annotations: [/* optional seed */],
});

const authoring = createAnnotationAuthoring(container, chart, {
  enableContextMenu: true,
});
// authoring.addVerticalLine(x);
// authoring.exportJSON(); authoring.undo(); authoring.redo();
// cleanup: authoring.dispose(); chart.dispose();

Full demo: annotation-authoring example.

Performance tips

  • Keep visible annotations under ~30; batch changes in one setOption.
  • Use belowSeries for bands and reference lines; aboveSeries for peaks and HUD.
  • Prefer stable id fields when you patch annotations from your app state.

Related