PercentileTrace
PercentileTrace traces one entity's percentile rank over time against the fixed bands of the pack.
- encodes
- line position on a locked 0–100 percentile scale
- precision
- high — rank is the axis, so the population bands are exact by definition
- nodes
- ≤ 6
PercentileTrace traces one entity's percentile rank over time on a scale locked to 0–100. Because the axis is rank, the population is constant by definition: the middle-half (p25–75) and near-full (p5–95) bands are fixed fields, exact by construction rather than estimated from the traced series, and the only line on the chart is the entity itself. The axis is never truncated, which would hide how much headroom or floor is left.
Install
import { PercentileTrace } from "@microcharts/react/percentile-trace";// ranks — real values under “Sample data” below<PercentileTrace data={ranks} title="Standing" />Sample data
// a weekly standing that drifts up from the middle half into the top bandconst ranks = [40, 46, 52, 58, 63, 68, 72, 76, 79, 81];Try it
When to use it
Use it for one player's or product's rank drifting over time, for whether a standing has crossed into the top or bottom of the pack, and for a percentile KPI where the population context matters. For a raw value over time use Sparkline; for one absolute number against a target use Bullet or Delta.
Sizing
Variants
The endpoint dot carries valence. By default a rising standing is good, so it turns positive; set positive="down"
when slipping down the pack is the win, as with a support ticket's backlog rank. The line already encodes direction,
so color is a redundant cue and never the only signal.
Edge cases
A single reading is a lone endpoint with no line to draw. It still reports its standing and holds the accessible-name
contract. Ranks outside 0–100 are clamped to the axis (a value of 102 reads as p100) and warn once in development.
With a locale, the percentile label and every announced number follow that locale's own formatting: de-DE renders
p81,5 with a comma.
Four homes
Accessibility
The accessible name states the current percentile, the change from the first reading, and how the standing moved relative to the middle half — "p81 now, up 41 points from the first reading; moved above the middle half." The interactive entry steps the readings and announces each one's percentile.
The interactive entry follows the shared interaction contract:
arrow keys rove between units on both axes, Home and End jump to the ends, and a click, tap, Enter or
Space selects a unit — pinning its readout so it survives blur, until you select it again or press Escape.
On touch, a tap pins and a drag scrubs.
Props
| Prop | Type | Notes |
|---|---|---|
| data* | number[] | Percentile ranks 0–100, one per reading; out-of-range values are clamped. |
| showBands | boolean | Draw the fixed p25–75 and p5–95 population fields (default true). |
| positive | "up" | "down" | Which direction is good — colors the endpoint dot (default up). |
| label | "last" | "none" | Final percentile in a right gutter. |
| unit | string | interactiveReading noun for the interactive announcement (default 'step'). |
| animate | boolean | interactiveOpt-in entrance motion when the chart mounts client-side — add import "@microcharts/react/motion" once. Inert on the server, on hydrated server HTML, and under prefers-reduced-motion. |
Plus the shared grammar — data, domain, color, title, summary, format — and the layout props (width, height, className, style) that every chart accepts. Interactive entries also share animate and live, and — wherever a chart has more than one navigable unit — onActive, onSelect, selectedIndex and defaultSelectedIndex; and — wherever the chart shows a hover value — readout. See the shared grammar.