Annotations

Annotations give the reader something to compare the data against: a limit, a normal range, the moment a deploy landed. They're plain children (<Threshold>, <TargetZone>, <Marker>, <Callout>) that the host chart draws in its own coordinate space, so the same child lands identically on any chart that accepts it. Reference ink stays quieter than data ink: hairlines stroke at 0.7 opacity, labels take the muted --mc-neutral label ink, and a target band uses the same faint --mc-band fill the charts do.

Install

The annotation layer is its own ~1.5 kB entry. The mark renderers ship with this import, so a host that renders no annotations pays only a small children walker.

import { Threshold, TargetZone, Marker, Callout } from "@microcharts/react/annotations";

The vocabulary

• <Threshold y={65} label="SLA" /> — a dashed reference hairline at a data-space y.
• <TargetZone y={[40, 60]} /> — a normal-range band, always drawn beneath the data ink. It takes a label too.
• <Marker x={8} label="deploy" /> — a vertical moment mark; x addresses the host's primary axis (the data index on index-based charts like Sparkline and SparkBar).
• <Marker x={8} celebrate /> — six deterministic particles burst once on entrance, for milestone crossings only; under reduced motion they render as a static starburst.
• <Callout x={5} y={45} label="dip" /> — a labeled point on an elbow hairline. label is required; y is optional and defaults to the frame's mid-height.

label is optional on the other three, and all four take a color to override the reference ink on that one mark. A fragment works as a container (<><Threshold … /><Marker … /></>); the host's walker unwraps it.

The same child, any host

Annotation children carry no chart-specific geometry; they resolve against the host's scale. Move the exact <TargetZone> and <Threshold> from a line onto bars and they land in the same data-space, unchanged.

Every value-series host

Every value-series chart hosts annotations: the charts with a continuous value axis and an index / slot / time x-axis, where a data-space x and y map cleanly onto the frame. That's Sparkline, SparkBar, MiniBar, CyclePlot, CitySkyline, ChangePoint, DualSparkline, SpreadBand, ForecastCone, ControlStrip, QueueDepth, BurnChart, Waterfall, PercentileTrace, RetentionCurve, WinProbWorm, ErrorBudget, NetFlow, Horizon, EnsembleGhosts, PairedBars (vertical), and Slope. The same <Threshold> or <Marker> lands in each chart's own data-space, unchanged. (MiniBar and PairedBars host in their default vertical orientation, where value lives on the y-axis; a horizontal layout flips the axes, so annotation children pass through.)

Charts without a single continuous value axis don't host them: there's no shared y for a <Threshold> to land on.

Most still accept children as a plain pass-through, so an annotation placed inside one renders nothing and warns in dev. A few take no children at all, Delta among them, and passing one is a type error.

Rendering rules

• A coordinate outside the host's domain clamps to the edge at 0.4 opacity, so it reads as off-scale instead of being dropped.
• Annotations never change the auto summary, which describes the data alone. To describe an annotation on a static chart, pass an explicit summary string.
• celebrate particles are seeded from the marker's x and the host's size, never Math.random, so server and client render the same burst.
• A label you supply is the one text the containment rule can't pre-reserve a gutter for, so two mechanisms keep it inside the chart. Threshold, TargetZone and Callout truncate: a label longer than its available run is cut and given a trailing …. Marker flips its anchor instead, drawing a label near the right edge leftward from the mark, so a moment mark never loses characters.
• Reference hairlines draw at a fixed 1-unit weight, exempt from --mc-density, so tightening the density never thickens the context ink along with the data. The Callout elbow is the exception, drawn a shade lighter at 0.75, because it's a leader line pointing at data rather than a reference the reader measures against.