Annotations & emphasis

Three ways to draw attention

Tool	Builder	What it does
Highlights	`highlight()`	De-emphasise everything that doesn’t match a predicate, so the matched observations stand out
Reference lines	`geom.rule()`	Draw a constant line — a goal, threshold, or baseline — that the scale grows to fit
Annotations	`annotation.*`	Layer callouts on top of the plot: difference arrows, shaded regions, text, arrows, and more

Each is a spec feature, so it composes left-to-right in pipe like any geom or scale, and re-resolves on every compile — annotations track the data they’re pinned to, and rules extend the axis domain.

pipe(
  createSpec({ x: 'month', y: 'revenue', color: 'region' }),
  geom.line(),
  scale.x.discrete(),
  scale.y(),
  scale.color.palette(),
  highlight({ variable: 'region', eq: 'EU' }), // emphasis
  geom.rule({ aes: { y: { value: 2500 } }, params: { label: 'Target' } }), // reference line
  annotation.shape({
    region: { anchorType: 'panel', x: 0.75, y: 0, width: 0.25, height: 1 },
    fillColor: '#e15759',
    fillOpacity: 0.1,
  }) // callout
);

Highlights

Predicate-driven emphasis: pick observations, series, or a whole x-slice.

Reference lines

Goal lines, thresholds, and baselines with geom.rule().

Annotations

Difference arrows, shaded regions, text, and pinned dots.

Highlight vs. annotation vs. reference line

They overlap in spirit but differ in mechanism:

Reach for a highlight when the emphasis is about the data — “show me the EU series,” “dim everything below target.” The predicate selects real observations, so it survives data changes and re-sorts.

Reach for a reference line when you’re marking a constant value the data should be read against — a sales goal, a capacity ceiling, a zero baseline.

Reach for an annotation when you’re adding a layer the data doesn’t contain — a label explaining a spike, an arrow between two points, a shaded “forecast” band.

Get Started

Core concepts

Chart types