Annotations & emphasis

Graphy has three tools for directing attention. All three are piped into the spec next to your geoms and scales.

Three ways to draw attention

Tool	Builder	What it does
Highlights	`highlight()`	De-emphasize 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 over the plot: difference arrows, shaded regions, text, arrows, images, stickers, pinned numbers and comments

Each is a spec feature. It composes left to right in pipe like any geom or scale, and it resolves again on every compile: annotations follow the data they are 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.discrete(),
  highlight({ variable: 'region', eq: 'EU' }), // emphasis
  geom.rule({ aes: { y: { value: 2500 } }, params: { label: 'Target' } }), // reference line
  annotation.shape({
    id: 'forecast',
    region: { anchorType: 'panel', x: 0.75, y: 0, width: 0.25, height: 1 },
    zOrder: 'background',
  }), // callout
  styles({
    overrides: [
      style.annotation.shape(
        { fill: '#e15759', alpha: 0.1 },
        { annotation: 'forecast' }
      ),
    ],
  })
);

Highlights

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

Reference lines

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

Annotations

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

Highlight vs. annotation vs. reference line

They overlap in purpose but differ in mechanism:

Use a highlight when the emphasis is about the data: “show me the EU group”, “dim everything below target”. The predicate selects real observations, so it survives data changes and re-sorts.
Use a reference line to mark a constant value the data is read against: a sales goal, a capacity ceiling, a zero baseline.
Use an annotation to add something the data does not contain: a label explaining a spike, an arrow between two points, a shaded “forecast” band.

Get Started

Core concepts

Chart types

Themes