Annotations

Annotations layer callouts on top of the plot — a shaded region, a labelled arrow, a note pinned to a spike. They carry information the data doesn’t contain, and the annotation builder pipes them into the spec like any other feature. Because they’re a spec feature, annotations re-resolve on every compile: panel-anchored ones re-flow when the chart resizes, and data-anchored ones move with the observation they’re pinned to.

Anchoring

Every annotation is positioned by an anchor that describes a relationship to the graph, not a fixed pixel. There are two frames:

Panel — a fraction of the plot rectangle, [0, 1] from the top-left. { anchorType: 'panel', x: 0.5, y: 0 } is the top-centre. Panel anchors don’t snap to data, so they hold their place as the data changes.
Observation — pinned to a single data point by its anchorValue (the x-value) and optional groupValue (the series). The annotation follows that observation wherever it lands.

// floats at the top-centre of the plot
{ anchorType: 'panel', x: 0.5, y: 0 }

// pins to the 'Jun' point of the 'North' series
{ anchorType: 'observation', anchorValue: 'Jun', groupValue: 'North' }

Region-based annotations (shapes, images) take a panel rectangle — { anchorType: 'panel', x, y, width, height } — and point/observation annotations take a single anchor. An observation anchor also accepts an align (which edge or corner of the observation to attach to) and an offset (a nudge in panel fractions or pixels). On a combo chart, more than one layer can hold the same (anchorValue, groupValue) pair — bars and a trend line both have a value at 'Jun'. Name the layer you mean and pass its id as layerId:

pipe(
  createSpec({ x: 'month' }),
  geom.bar({ id: 'bars', aes: { y: 'sales' } }),
  geom.line({ aes: { y: 'trend' } }),
  annotation.pinnedNumber({ at: { layerId: 'bars', anchorValue: 'Jun' } })
);

Omit layerId and the anchor resolves against the first layer that matches. An id no layer carries drops that annotation with a warning rather than silently moving it.

The annotation kinds

Each method on annotation appends one callout. Multiple calls of the same kind accumulate.

Method	What it draws
`annotation.differenceArrow()`	A labelled delta between two observations — reads the measured gap and labels it as an absolute, relative, or proportional change
`annotation.shape()`	A shaded rectangle over a panel region — the classic “forecast” or “recession” band
`annotation.arrow()`	A free-standing arrow between two point anchors, each floating or pinned
`annotation.text()`	A free rich-text label
`annotation.image()`	An image placed in a panel region
`annotation.sticker()`	A built-in emoji-like sticker pinned to a point
`annotation.pinnedNumber()`	A dot on one observation; its value shows in a mini view, full tooltip on hover
`annotation.comment()`	A dot on one observation carrying rich-text content

Difference arrow

A difference arrow spans two observations and labels the change between them — you choose what the label measures:

annotation.differenceArrow({
  start: { anchorValue: 'Jan', groupValue: 'North' },
  end: { anchorValue: 'Jun', groupValue: 'North' },
  label: 'relative-difference', // 'absolute-difference' | 'relative-difference' | 'proportion'
});

Distinct from annotation.arrow(), which is a plain arrow between two positions you specify — it doesn’t read any data.

Shaded region

annotation.shape({
  region: { anchorType: 'panel', x: 0, y: 0.7, width: 1, height: 0.3 },
  fillColor: '#e15759',
  fillOpacity: 0.12,
  zOrder: 'background', // beneath the geoms; 'foreground' draws on top
});

zOrder decides whether a shape or image sits behind the data ('background', the usual choice for a wash of color) or in front of it ('foreground').

Text

A text annotation takes a rich-text node and a top-left point anchor. width is a fraction of the plot width; height follows the content:

annotation.text({
  content: {
    type: 'doc',
    content: [
      {
        type: 'paragraph',
        content: [{ type: 'text', text: 'Product launch' }],
      },
    ],
  },
  at: { anchorType: 'panel', x: 0.4, y: 0.1 },
  width: 0.25,
});

Image

Place an image in a panel region. fit decides how it scales inside the box — 'fill' stretches, 'contain' letterboxes, 'cover' crops to fill:

annotation.image({
  src: 'https://example.com/logo.png', // URL or data URI
  region: { anchorType: 'panel', x: 0.05, y: 0.08, width: 0.24, height: 0.5 },
  fit: 'contain', // 'fill' | 'contain' | 'cover'
});

Like a shape, an image also takes an optional zOrder ('background' or 'foreground') and an opacity in [0, 1].

Sticker

A sticker pins a built-in emoji-like image to a single observation. Give it a sticker id from the catalogue and an observation anchor — it then travels with its data point through re-sorts and filters:

annotation.sticker({
  sticker: 'rocket', // 'rocket' | 'thumbs-up' | 'thumbs-down' | 'clapping-hands' | 'grinning-face' | …
  at: { anchorType: 'observation', anchorValue: 'Q4' },
});

Reference lines — for marking a constant value rather than a region
Content — the rich-text node shape used by text and comment annotations
Mappings & aesthetics — the series and x-values an observation anchor names

Get Started

Core concepts

Chart types

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

Anchoring

The annotation kinds

Difference arrow

Shaded region

Text

Image

Sticker

​Anchoring

​The annotation kinds

​Difference arrow

​Shaded region

​Text

​Image

​Sticker

​Related

Anchoring

The annotation kinds

Difference arrow

Shaded region

Text

Image

Sticker

Related