`). Nothing to wire; it just has a name. * **Explicit `id`** — pass an `id` and the chart upgrades to a `<title>`/`<desc>` pair referenced by `aria-labelledby`, the richest form, for when you want the title and description addressable. Override the whole sentence with a string when you have better words than the generator: ```tsx <Sparkline data={data} summary="Revenue per week, Q3 — up 40% and accelerating." /> ``` ## Decorative opt-out [#decorative-opt-out] When the surrounding text already describes the data — the common case for a word-sized chart *inside* a sentence — mark the chart decorative with `summary={false}` so screen readers skip the redundancy rather than reading it twice. ```tsx <p> Revenue climbed steadily <Sparkline data={data} summary={false} /> through the quarter. </p> ``` A decorative chart renders `aria-hidden="true"` instead of `role="img"` — it leaves the accessibility tree entirely, and no `<title>` or `<desc>` is emitted. On an `/interactive` entry the same call resolves the name: with nothing left to announce, the wrapper drops `role="img"` and `tabIndex={0}` and takes `aria-hidden="true"` instead — so there's nothing to tab to or activate, and the static and interactive entries tell one story. ## One interaction contract [#one-interaction-contract] The `/interactive` entries share a single contract across the catalog: learn it on a Sparkline and it already holds on an ActivityGrid, a Dumbbell, or a Waterfall. What differs between charts is only what a *unit* is — a point, a bar, a day cell, a segment, a pair — and each chart's page names its own. **Roving focus, one tab stop.** A chart is one focusable element (`role="img"`, `tabIndex={0}`), never a tab trap of one stop per data point. Arrow keys rove between units: **←/↑** move to the previous unit, **→/↓** to the next — both axes, so a grid navigates the same way a line does. **Home** and **End** jump to the first and last unit. **Active vs selected.** Hovering or roving makes a unit *active* — a transient read that clears when the pointer leaves or focus blurs. **Enter** or **Space** (or a click, or a tap) *selects* it, which **pins** the readout so it survives blur and pointer-leave — a keyboard user can move focus elsewhere and the pinned value stays on screen. Selecting the same unit again clears it, and **Escape** clears the selection from anywhere. The two states are visually distinct, so "where I am" and "what I kept" never read as the same thing. **Touch.** A tap pins a unit exactly like a click; dragging across the chart scrubs the active unit continuously. A drag is treated as a scrub, never mistaken for a tap, so scrolling past a chart can't pin a value by accident. **Announcements.** Every change of active or selected unit is written into a polite live region, so a keyboard or screen-reader user reads the same detail a mouse user gets from the hover chip. The picker fires only when the *unit* changes, not on every pointer move, so sweeping across a chart announces once per unit crossed rather than once per pixel. The callbacks mirror the states exactly. `onActive` fires as the active unit changes; `onSelect` fires on selection. Both receive a `MicroDatum` — `{ index, value, label?, formatted? }`, where `index` identifies the unit, `value` is that unit's primary encoded number (`null` when the unit encodes nothing), and `formatted` is the exact string the chart's own readout chip would show — or `null` when the chart clears. Selection is controllable with `selectedIndex`, or seeded once with `defaultSelectedIndex`. To move the value out of the chart entirely — a KPI number, a sentence, a cell that updates as you hover — set `readout={false}` to keep the crosshair but drop the in-chart chip, and render `datum.formatted` from `onActive` yourself. Charts with only **one** unit — Delta, Progress, StatusDot, Bullet, and the rest of the scalar set — have nothing to rove between, so they take `onSelect` alone (click, tap, Enter, or Space) and carry no selection state. **Values that change on their own.** Fifteen single-value charts built for updating KPI cards take `live` (default `true`): when the value changes, the new reading is re-announced through the polite region without anyone touching the chart. Set `live={false}` to silence it. A few throttle that announcement so a streaming value never floods the buffer: | Chart with `live` | Announcement throttle | | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | Progress | whole-percent steps only | | MoonPhase, FillWord | at most once per second | | Delta, ProgressRing, StatusDot, TrendArrow, Thermometer, Hourglass, FatDigits, TallyMarks, DicePips, Honeycomb, PictogramRow, BalanceBeam | none — every change announces | Two charts throttle without taking `live` at all: **EtaBar** and **TapeGauge** re-announce their reading as it changes, but never more often than `announceEvery` milliseconds — 10 s and 5 s by default, and tunable per instance. Three charts sit outside the contract, deliberately: **MinimapStrip** is a viewport-window slider (`role="slider"`, with its own `onWindowChange([lo, hi])` range payload), **TokenConfidence** flows as inline HTML text and moves real focus onto each *flagged* token span — confident tokens carry no mark and are skipped — and **WindBarb** ships static-only. Static entries carry no listeners at all; every bit of this is opt-in. ## Color is never the only channel [#color-is-never-the-only-channel] Direction and state are always doubled, so a chart survives with no color at all: * **Delta** pairs a ▲/▼ glyph with its color — the glyph carries the sign. * **SparkBar** encodes sign by *position* above or below the baseline, not hue. * **ActivityGrid** always ships a numeric summary alongside its intensity ramp. The default stroke tokens are chosen against a **4.5:1 contrast** target on the page backgrounds they're designed for, and the dark values are hand-tuned per token rather than inverted, so nothing washes out in dark mode. Contrast against *your* surface is still yours to check — charts paint no background, so a mark inherits whatever you place it on. ## Internationalization and RTL [#internationalization-and-rtl] Nothing about a chart is hard-coded to English or to left-to-right layout. * **Localized numbers.** Every rendered number and every number in the summary goes through `Intl.NumberFormat`. Pass `locale` and `format` and the digits, grouping, and units follow the reader's locale: ```tsx <Sparkline data={data} locale="de-DE" format={{ style: "currency", currency: "EUR" }} /> ``` See [Formatting & scale](/docs/formatting) for the full `format` / `locale` story, including the exported `makeFormatter` helper for matching your prose numbers to a chart's. * **Localized words.** The summary templates are a swappable contract (`SummaryStrings`; the English set ships as the exported `EN` dictionary). Spread `EN`, override the keys you're translating, and pass the result as `strings` — static and `/interactive` entries both accept it, so a server-rendered chart localizes without shipping any client JavaScript. Or override the whole sentence with a `summary` string. Either way the accessible name, the live-region announcements, and the readout chip on an interactive entry all speak your language, because all three read from the same dictionary. Six charts don't take `strings` on their static entry: Sparkline, ActivityGrid, and MusicStaff accept it on the `/interactive` entry only, while SparkBar, Delta, and Bullet compose their sentence inline — `summary` is the translation seam there. `summary` and `strings` stay the entire text surface, and that is now enforced rather than asserted. A guard renders 22 interactive entries — the readouts are where the drift lives, and they only exist in a browser — each with a `strings` object of sentinel tokens, and fails on any English left in the output. It was written because the claim had quietly stopped being true: readouts had accumulated words like "median", "vs" and "queued" in component code, which is exactly the drift a guard catches and a promise does not. The generator itself is exported too: `import { describeSeries } from "@microcharts/react"` returns the exact sentence for a series, handy for tests, tooltips, or feeding a model. * **RTL layouts.** A chart is direction-neutral SVG with a localized text name, so it drops into an RTL document without breaking — it's an `img`, not a run of text. Time-ordered charts keep their conventional oldest-to-newest reading order; you localize the summary and the number formatting, which is what a screen-reader user actually hears. ## System preferences, handled [#system-preferences-handled] * **`prefers-reduced-motion`** — entrance and update animations resolve instantly to their final state. Static charts have no `animate` prop and run no JavaScript animation; the one thing that moves inside a static host is `<Marker celebrate>`, whose particle burst is a pure-CSS one-shot that reduced motion also stills. * **`forced-colors`** — data ink maps to system `CanvasText`, accents to `Highlight`, muted marks to `GrayText`, so a Windows High Contrast user sees a correct chart, not a blank box. * **`prefers-contrast`** — strokes thicken and bands deepen automatically. ## Verify it yourself [#verify-it-yourself] Because the summary is deterministic and the markup is plain SVG, accessibility is testable in CI, not a manual audit: ```tsx import { axe } from "vitest-axe"; const { container } = render(<Sparkline data={data} title="Revenue" />); expect(await axe(container)).toHaveNoViolations(); // and assert the exact announced sentence: expect(container.querySelector("[role=img]")).toHaveAccessibleName( "Revenue. Trending up 200%. Range 3 to 9. Last value 9.", ); ``` # AI-native (/docs/ai) Most chart libraries are written for a human with a mouse. microcharts is written so a **model** can draw a chart mid-sentence and a **person** can trust it. Two properties make that work: every chart renders from plain `data`, and every chart carries a generated, human-readable summary — the same sentence a screen reader speaks, a crawler indexes, and a model can quote back. Nothing is hidden in pixels, so a few tokens of text become a real, accessible instrument. > Above is the real thing, not a video: a scripted reply streams in, and the chart syntax it emits becomes shipped microcharts the instant each fence closes. Everything below is the contract behind it. The AI reply is the newest home for a word-sized chart, not the only one — the same component lives in a product UI, a rendered report, and inline in docs like these. This page is the model-facing contract; [Where they live](/docs#where-they-live) shows the rest. ## The grammar [#the-grammar] A model emits a chart in one of two forms — both deliberately forgiving, the kind of thing a model produces reliably mid-stream. Pick a type and a form to see exactly what it writes, what it renders, and the React it's equivalent to: The grammar has two forms — a fenced `microchart` block for a standalone chart, or an inline `microchart <type> <data>` span inside a sentence. Body is whitespace/comma numbers, or key=value for composites. **Sparkline** — trend over time ```microchart sparkline 132 148 141 165 159 182 176 203 ``` Equivalent React: ```tsx <Sparkline data={[132, 148, 141, 165, 159, 182, 176, 203]} title="Revenue" /> ``` **SparkBar** — magnitude per period (signed values = win/loss) ```microchart sparkbar 6 9 5 11 7 12 8 10 ``` Equivalent React: ```tsx <SparkBar data={[6, 9, 5, 11, 7, 12, 8, 10]} title="Deploys per day" /> ``` **Delta** — one signed change or ratio ```microchart delta +0.184 ``` Equivalent React: ```tsx <Delta value={0.184} title="Week over week" /> ``` **Bullet** — a value against a target (value= target= bands=) ```microchart bullet value=72 target=80 bands=50,90 ``` Equivalent React: ```tsx <Bullet value={72} target={80} bands={[50, 90]} title="Quota attainment" /> ``` **ActivityGrid** — cadence / intensity over a period ```microchart activity 0 2 1 3 4 2 1 3 2 4 3 2 ``` Equivalent React: ```tsx <ActivityGrid data={[0, 2, 1, 3, 4, 2, 1, 3, 2, 4, 3, 2]} layout="strip" title="Commit activity" /> ``` The body is whitespace- or comma-separated numbers for series charts, or `key=value` pairs for composites. These five cover the questions an assistant answers most — *trend, magnitude, change, attainment, cadence* — but the same pattern extends to [any chart in the catalog](/docs/charts): name a type, pick a body convention, map it to that chart's import. ## Wire it up [#wire-it-up] Turning the grammar into components is a parser and a `switch` — no framework, a few lines. ### Parse the stream [#parse-the-stream] Pull fenced blocks and inline spans out of partially-streamed Markdown. A fence that hasn't closed yet stays raw, then morphs the moment it does. ```ts const FENCE = /```microchart (\w+)\n([\s\S]*?)```/g; const INLINE = /`microchart (\w+) ([^`]+)`/g; const nums = (b: string) => b.split(/[\s,]+/).map(Number).filter(Number.isFinite); const kv = (b: string) => Object.fromEntries( b.split(/\s+/).flatMap((t) => { const i = t.indexOf("="); return i > 0 ? [[t.slice(0, i), t.slice(i + 1)]] : []; }), ); ``` ### Map type → component [#map-type--component] One `switch`. Because geometry is pure and charts render from `data` alone, the model's chart is identical to one you'd write by hand. ```tsx import { Sparkline } from "@microcharts/react/sparkline"; import { SparkBar } from "@microcharts/react/sparkbar"; import { Delta } from "@microcharts/react/delta"; import { Bullet } from "@microcharts/react/bullet"; import { ActivityGrid } from "@microcharts/react/activity-grid"; export function ChartBlock({ type, body }: { type: string; body: string }) { switch (type) { case "sparkline": return <Sparkline data={nums(body)} title="Series" />; case "sparkbar": return <SparkBar data={nums(body)} title="Per period" />; case "delta": return <Delta value={Number(body.trim())} title="Change" />; case "bullet": { const p = kv(body); return ( <Bullet value={+p.value} target={p.target ? +p.target : undefined} bands={p.bands?.split(",").map(Number)} title="Attainment" /> ); } case "activity": return <ActivityGrid data={nums(body)} layout="strip" title="Cadence" />; default: return null; // unknown type → leave the text as-is } } ``` ### Render inline vs block [#render-inline-vs-block] An inline chart is decorative — the sentence describes it, so pass `summary={false}`. A standalone chart keeps its summary; give it a `title`. Wrap every inline SVG mark in `className="mc-inline"` — the class ships in `@microcharts/react/styles.css` (imported once in the Quickstart). It seats the mark on the text baseline, so it rides the line like a word in any font. Leave `Delta` bare; it is a text metric and owns its own baseline already. ```tsx NVDA closed +3.8%{" "} <span className="mc-inline"> <TrendArrow value={0.038} summary={false} /> </span>{" "} on the session — up <Delta value={0.038} summary={false} /> week over week. ``` ## Prompt the model [#prompt-the-model] A few lines teach the grammar. Reach for the technique that matches how the model is driven — structured output and tool calls first, since that's how most agents run today: #### Structured JSON The default for anything production. Have the model return JSON and map it yourself — no parsing of prose. Constrain `type` to an enum and the output is always renderable. ```tsx type ChartSpec = | { type: "sparkline" | "sparkbar" | "activity"; data: number[]; title?: string } | { type: "delta"; value: number; title?: string } | { type: "bullet"; value: number; target?: number; bands?: number[]; title?: string }; // model returns ChartSpec (JSON mode / response_format) → render directly function Chart(spec: ChartSpec) { switch (spec.type) { case "sparkline": return <Sparkline data={spec.data} title={spec.title} />; case "bullet": return <Bullet {...spec} />; // …one arm per type } } ``` #### Tool use Expose a single tool the model calls when a chart helps. Its arguments *are* the chart spec, so there's nothing to parse and the schema enforces the shape. ```ts const renderChart = { name: "render_chart", description: "Render a microchart when a number series helps the reader.", input_schema: { type: "object", required: ["type"], properties: { type: { enum: ["sparkline", "sparkbar", "delta", "bullet", "activity"] }, data: { type: "array", items: { type: "number" } }, value: { type: "number" }, target: { type: "number" }, bands: { type: "array", items: { type: "number" } }, title: { type: "string" }, }, }, }; // on tool_use → <Chart {...toolCall.input} /> ``` #### System prompt For free-form chat, drop this into the system message — enough for a capable model to emit valid blocks unprompted. ```text When a number series would help, emit a chart block instead of prose. Fenced for a standalone chart, inline `microchart …` for a word-sized one: ```microchart sparkline 132 148 141 165 159 182 176 203 ``` Types: sparkline · sparkbar (signed = win/loss) · delta (one signed ratio) · bullet (value= target= bands=) · activity (intensities). Never invent a pie or gauge — they aren't supported. ``` #### Few-shot When you want a specific house style, show one exchange. Models mirror the shape of the example. ```text User: How did deploys trend this week? Assistant: Steady, with a strong Thursday: ```microchart sparkbar 6 9 5 11 7 12 8 10 ``` User: And are we on track for the quota? Assistant: Close — `microchart delta +0.184` week over week puts us here: ```microchart bullet value=72 target=80 bands=50,90 ``` ``` #### Guardrails Never trust generated data blindly. Validate the type, coerce the numbers, and fall back to text when a block is malformed — the summary makes a graceful fallback trivial. ```ts const KNOWN = new Set(["sparkline", "sparkbar", "delta", "bullet", "activity"]); function safeBlock(type: string, body: string) { if (!KNOWN.has(type)) return null; // unknown type → render raw text const data = nums(body); if (type !== "delta" && data.length === 0) return null; // no numbers → skip return { type, body }; // charts handle empty/NaN/±∞ already } ``` ## Where it runs [#where-it-runs] A chart is plain text and JSON, so anything that reads or writes text can emit one and render it back — no SDK, no partnership, no island bridge. That spans the whole stack a model runs in today: the **chat assistants** that answer in prose, the **coding agents and IDEs** that scaffold the components from the typed catalog, and the **frameworks and SDKs** that wire tool-call output straight to charts. None of these is an integration we built — they work because the output is just text. - **Chat assistants & models** (emit a chart block mid-reply): Claude, ChatGPT, Gemini, Grok, DeepSeek, Kimi, Meta AI, Mistral, Perplexity, Qwen, Poe - **Coding agents & IDEs** (scaffold components from the typed catalog): Cursor, Claude Code, Codex, v0, opencode, Antigravity, Windsurf, Zed, Cline, Replit, Continue, Warp, Amp, Roo Code, StackBlitz, JetBrains AI, Pi, Copilot - **Frameworks & SDKs** (map tool-call output to charts): Vercel AI SDK, OpenAI Agents, LangChain, Anthropic SDK, Hugging Face, Ollama, Pydantic AI, CrewAI ## Integration scenarios [#integration-scenarios] Every path from model output to a rendered chart, with the one thing each needs. #### Streaming chat reply — morph blocks as they close Parse the partial Markdown on every token; render a fence as raw text until it closes, then swap in the chart. Word-sized charts land inside the sentence, standalone ones below it. The live demo at the top of this page is exactly this shape. ```tsx // on each streamed chunk: const nodes = parse(accumulatedText); // text | { type, body, closed } return nodes.map((n) => n.type === "text" ? <Inline text={n.v} /> : n.closed ? <ChartBlock type={n.type} body={n.body} /> : <pre>{n.raw}</pre>, // still streaming → show raw ); ``` #### React Server Components — zero client JavaScript Static entries are hook-free, so an RSC assistant renders the model's charts to HTML on the server. Nothing hydrates; the chart ships as markup. Add `/interactive` only where the reader needs to interrogate a value — hover, keyboard, touch, or click-to-pin — and read it back with `onActive` / `onSelect`. Every chart but WindBarb has an interactive twin; `catalog.json` names it per entry, so an agent never has to guess. ```tsx import { Sparkline } from "@microcharts/react/sparkline"; // no "use client" export default async function Answer({ spec }: { spec: ChartSpec }) { return <ChartBlock type={spec.type} body={spec.body} />; // pure SVG, server-rendered } ``` #### Tool / function-call output — rows straight to charts When a tool returns rows, render them instead of asking the model to describe them in prose — a `Sparkline` per row, a `Bullet` for a KPI against target. ```tsx {rows.map((r) => ( <tr key={r.id}> <td>{r.name}</td> <td><Sparkline data={r.history} summary={false} /></td> <td><Bullet value={r.value} target={r.goal} summary={false} /></td> </tr> ))} ``` #### Programmatic & React-free — outside a component tree Need a chart in a README, an email, or a non-React runtime? Render the static component to an SVG string on the server. Static entries are hook-free and listener-free, so the markup they emit stands on its own. ```ts import { renderToStaticMarkup } from "react-dom/server"; import { Sparkline } from "@microcharts/react/sparkline"; const svg = renderToStaticMarkup(<Sparkline data={data} title="Revenue" />); // → a self-contained <svg> string for anywhere HTML goes ``` #### Validation & safety — malformed data never breaks a render Every chart already handles the degenerate cases — empty, single value, all-equal, nulls, NaN, ±Infinity — with an honest short summary instead of a broken chart. Layer the type/coercion guardrails above and a bad block downgrades to plain text, never a crash. ## Machine-readable surfaces [#machine-readable-surfaces] Real, generated routes — the substance behind "AI-native", not a slogan. Point an agent here and it reads the true API instead of guessing. - [/llms.txt](/llms.txt): A hand-curated index of the docs for LLM tools, with explicit “does not support” notes to head off hallucinations. - [/llms-full.txt](/llms-full.txt): Every doc page concatenated into one text file — drop the whole API into a context window at once. - [/catalog.json](/catalog.json): Machine catalog: each chart’s name, import paths, data shape, and props (plus a shared-grammar block) — generated from the same registry that builds this site, and validated in CI against its JSON Schema. - [*.md mirrors](/docs/ai.md): Append .md to any docs page for a Markdown copy an agent reads without parsing HTML — every component expanded to text and code. The `.md` mirrors are real static files — `/docs/ai` has a sibling `/docs/ai.md` — so they resolve on any host, with no runtime, rewrite, or middleware. This site also deploys behind a small Cloudflare Worker that runs on `/docs/*` only: send `Accept: text/markdown` and the same doc URL returns the mirror inline, with `Vary: Accept` on both the Markdown and the HTML response. That negotiation is a convenience layered on top of the mirrors, never a dependency — appending `.md` always works. `/llms.txt` points at one more surface the cards don't: [`/agent-setup.md`](/agent-setup.md), the paste-and-run setup prompt for a coding agent, extracted from the [Quickstart](/docs/quickstart) so the two can't drift. Or skip the URL entirely: <CopyAgentSetup /> ## The whole contract, on one card [#the-whole-contract-on-one-card] Don't make a model memorize the catalog — [All charts](/docs/charts) files every type by the question it answers, and the [Charts index](/charts) shows them at a glance. Everything an agent needs to emit correct microcharts fits on one card — copy it straight into a system prompt: **Agent cheat sheet.** Grammar: - `microchart sparkline` — 132 148 141 165 159 182 176 203 (trend over time) - `microchart sparkbar` — 6 9 5 11 7 12 8 10 (magnitude per period (signed values = win/loss)) - `microchart delta` — +0.184 (one signed change or ratio) - `microchart bullet` — value=72 target=80 bands=50,90 (a value against a target (value= target= bands=)) - `microchart activity` — 0 2 1 3 4 2 1 3 2 4 3 2 (cadence / intensity over a period) Rules: - Import each chart from its own subpath — `@microcharts/react/<name>`; add `/interactive` only for hover and keyboard. - Static charts are hook-free — valid inside a React Server Component, zero client JavaScript. - Pass `data` and a `title`; the generated summary handles accessibility. Use `summary={false}` only when a chart is decorative inside describing text. - Never add a runtime dependency, and never reach for a pie or gauge — they aren't shipped. Surfaces: /llms.txt · /llms-full.txt · /catalog.json · *.md mirrors That's the entire surface area: a grammar a model already knows how to write, and charts a person can trust on sight. Point an assistant at [`/llms.txt`](/llms.txt) — or the fuller [`/llms-full.txt`](/llms-full.txt) and the machine-readable [`/catalog.json`](/catalog.json) — or start from the [Quickstart](/docs/quickstart) and render your first chart in minutes. # Annotations (/docs/annotations) Annotations answer "what should the reader compare this against?". 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 whispers: the 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 — so the data never competes with its context. ```tsx <TargetZone y={[40, 60]} /> <Threshold y={65} label="SLA" /> <Marker x={3} label="deploy" /> </Sparkline>`" > <Sparkline data="[48, 52, 45, 58, 51, 47, 55, 49, 71, 64, 57, 52]" title="p95 latency" width="200" height="48"> <TargetZone y="[40, 60]" /> <Threshold y="65" label="SLA" /> <Marker x="3" label="deploy" /> </Sparkline> ``` ## Install [#install] The annotation layer is its own \~1.5 kB entry. A host that renders no annotations pays only a tiny children walker; the mark renderers ship with this import. ```tsx import { Threshold, TargetZone, Marker, Callout } from "@microcharts/react/annotations"; ``` ## The vocabulary [#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 rest as a quiet starburst. * **`<Callout x={5} y={45} label="dip" />`** — one narrated 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. ```tsx <Marker x={9} celebrate label="10k!" /> </Sparkline>`" > <Sparkline data="[3, 4, 5, 5, 6, 8, 9, 11, 12, 14, 15, 17]" title="Signups" width="160" height="36"> <Marker x="9" label="10k!" /> </Sparkline> ``` ```tsx <Callout x={3} y={58} label="cache miss" /> </Sparkline>`" > <Sparkline data="[48, 52, 45, 58, 51, 47, 55, 49, 51, 46]" title="Latency" width="160" height="40"> <Callout x="3" y="58" label="cache miss" /> </Sparkline> ``` ## The same child, any host [#the-same-child-any-host] The children don't know which chart drew them — 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. ```tsx <TargetZone y={[3, 8]} /> <Threshold y={10} label="cap" /> </SparkBar>`" > <SparkBar data="[4, 7, 3, 9, 6, 8, 5, 11, 7, 9]" title="Deploys per day" width="160" height="44"> <TargetZone y="[3, 8]" /> <Threshold y="10" label="cap" /> </SparkBar> ``` ## Every value-series host [#every-value-series-host] Every **value-series** chart hosts annotations — the charts with a continuous value axis and an index / slot / time x-axis, so 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-y don't host them, by design — there's no shared `y` for a `<Threshold>` to land on: | Why it can't host | Examples | | ----------------------------- | ---------------------------------------- | | Scalar readout — no axis | Delta, FatDigits, StatusDot, Thermometer | | Part-to-whole — y is a share | MicroDonut, SegmentedBar, Funnel | | Value encoded as colour | HeatStrip, ActivityGrid, the calendars | | Value against value | QuadrantDot, MicroScatter, BiasStrip | | Pure timeline — no value axis | the event/phase timelines | Most still accept children as a plain pass-through, so an annotation placed inside one renders nothing and warns in dev; a few — Delta among them — take no children at all, and it's a type error. <AnnotationHostShowcase /> ## Honesty rules [#honesty-rules] * A coordinate outside the host's domain **clamps to the edge at 0.4 opacity** — visibly off-scale, never silently dropped. * Annotations never touch the auto summary: the data description stays pure. To narrate 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 it's kept inside the chart by one of two mechanisms. `Threshold`, `TargetZone` and `Callout` **truncate**: a label longer than its available run is cut and given a trailing `…`. `Marker` instead **flips its anchor** — a label near the right edge draws leftward from the mark rather than off the chart — so a moment mark never loses characters. * Reference hairlines draw at a fixed 1-unit weight, deliberately exempt from `--mc-density`, so tightening the density never thickens the context ink along with the data. The one exception is the `Callout` elbow, drawn a shade lighter at 0.75, because it's a leader line pointing at data rather than a reference the reader measures against. # Composition (/docs/composition) microcharts are built to sit *inside* an interface, not in a chart pane of their own. This page documents the placement decisions the gallery demos make — the surface they need, the size and props each context wants, and how to compare several at once — so nothing is left implied. If a demo on this site looks right, this is why. ## Charts sit on your surface [#charts-sit-on-your-surface] Every chart is transparent: it **never paints its own background**. That's deliberate — a chart drops onto whatever surface it lands on and picks up the ink color from `--mc-stroke` (which tracks light/dark for you). The one decision that's yours: give it a container with real contrast. * Put the chart on a surface with enough contrast for a 1.5 px line — the data, valence, and accent inks all clear 4.5:1 on the built-in light and dark themes. (`--mc-neutral`, the muted context ink for baselines and ghost marks, sits at 3.5:1 — comfortably past the 3:1 bar for non-text, and deliberately quieter than the data.) * Don't wrap it in a low-contrast tint and expect the chart to compensate; it won't, by design. * Need the ink to differ from the page (charts on a colored panel, frosted glass)? Set `--mc-stroke` (and valence tokens if needed) on the container — see [Theming](/docs/theming#frosted-or-translucent-surfaces). Don't override `.mc-root` paint rules. > The gallery renders each demo inside a panel with a normal card background and a hairline border. Nothing about that panel is part of the library — it's just a surface. Your app's cards, table rows, and headers are surfaces too. ## In a sentence [#in-a-sentence] A word-sized chart in running prose scales with the **font** and aligns to the text baseline; drop its endpoint dots and it reads as one glyph, not a widget. (There are no axes to drop — no chart in the catalog draws one.) Wrap it in `mc-inline` (shipped in `styles.css`), pass `dots="none"`, and mark it decorative with `summary={false}` so a screen reader hears the sentence, not a second description. ```tsx p95 latency this week{" "} <span className="mc-inline"> <Sparkline data={latency} dots="none" summary={false} width={64} height={16} /> </span>{" "} — trending down. </p>`" > {/* Text as JSX expressions ({"…"}), never bare prose: MDX blockifies multiline bare text inside a JSX <p> into nested <p>s (hydration error). Expressions also survive prettier's md/mdx prose-wrap, which re-expands a single line. */} <p className="max-w-md text-[0.95rem] leading-relaxed"> {"p95 latency this week "} <span className="mc-inline"> <Sparkline data="[48, 45, 44, 40, 38, 36, 33, 31]" dots="none" summary="false" width="64" height="16" /> </span> {" — trending down."} </p> ``` See [Sizing](/docs/sizing#inline-in-a-sentence) for the `em`-based variant that scales with the surrounding type size. ## In a table cell [#in-a-table-cell] In a dense table, each row already carries a name and a number — the chart's job is the *shape* between them. So it goes small, with dots off, decorative (`summary={false}`), and the numeric column stays `tabular-nums` so figures line up. ```tsx <td>checkout-api</td> <td><Sparkline data={latency} dots="none" summary={false} width={64} height={18} /></td> <td className="tabular-nums">31 ms</td> </tr>`" > <table className="w-full max-w-sm text-sm tabular-nums"> <tbody className="[&>tr+tr]:border-t [&>tr+tr]:border-fd-border/60"> {[ { name: "checkout-api", data: [48, 45, 44, 40, 38, 36, 33, 31], now: "31 ms" }, { name: "auth-api", data: [12, 13, 12, 14, 13, 15, 14, 16], now: "16 ms" }, { name: "search-api", data: [80, 78, 82, 79, 81, 80, 79, 78], now: "78 ms" }, ].map((s) => ( <tr key={s.name}> <td className="py-1.5 pr-3 text-fd-muted-foreground">{s.name}</td> <td className="py-1.5"> <Sparkline data={s.data} dots="none" summary={false} width={64} height={18} /> </td> <td className="py-1.5 pl-3 text-right text-fd-muted-foreground">{s.now}</td> </tr> ))} </tbody> </table> ``` ## In a KPI card [#in-a-kpi-card] Here the big number leads and the chart is context beneath it. Give it a little more height, turn `fill` on so it reads as a filled area at a glance, and keep it decorative — the figure and label already say what it is. ```tsx <span className="figure">1,600</span> <span className="unit">concurrent, now</span> <Sparkline data={connections} fill summary={false} width={120} height={32} /> </div>`" > <div> <div className="text-fd-muted-foreground text-xs"> Active connections </div> <div className="mb-1 flex items-end gap-2"> <span className="text-3xl tabular-nums"> 1,600 </span> <span className="mb-1 text-fd-muted-foreground text-xs"> concurrent, now </span> </div> <Sparkline data="[1240, 1310, 1290, 1420, 1380, 1510, 1470, 1600]" summary="false" width="120" height="32" /> </div> ``` ## In a tab or button [#in-a-tab-or-button] A spark beside a label previews what's behind the tab. It goes *tiny* — the label is the primary read, the chart a hint — so drop to a small box with no dots. ```tsx CPU <Sparkline data={cpu} dots="none" summary={false} width={40} height={14} /> </button>`" > <div className="flex flex-wrap gap-1.5"> {[ { name: "CPU", data: [62, 65, 61, 68, 70, 66, 72, 75], on: true }, { name: "Memory", data: [48, 47, 49, 46, 45, 44, 43, 42], on: false }, { name: "Network", data: [120, 118, 122, 119, 121, 120, 119, 118], on: false }, ].map((m) => ( <span key={m.name} className={`inline-flex items-center gap-2 rounded-md border px-2.5 py-1.5 text-sm ${ m.on ? "border-fd-primary/40 bg-fd-primary/5 text-fd-foreground" : "border-fd-border text-fd-muted-foreground" }`} > {m.name} <Sparkline data={m.data} dots="none" summary={false} width={40} height={14} /> </span> ))} </div> ``` ## Small multiples: one shared scale [#small-multiples-one-shared-scale] The most important composition decision, and the easiest to get silently wrong: when you place several sparklines in a row to *compare* them, they must share one vertical scale. Auto-scaling each to its own range makes a flat line and a spiking one look identical — a real correctness bug. `SparkGroup` fixes it structurally. It reads every child's `data`, computes **one** domain across all of them, and enforces **one** physical size — so a row of charts is honestly comparable. It's hook-free and RSC-safe, and any child's own explicit `domain`/`width` still wins. ```tsx <Sparkline data={us} summary={false} /> <Sparkline data={eu} summary={false} /> <Sparkline data={apac} summary={false} /> </SparkGroup>`" > <SparkGroup width="80" height="22"> <Sparkline data="[20, 22, 21, 24, 23, 25, 24, 26]" summary="false" /> <Sparkline data="[60, 58, 62, 59, 61, 60, 59, 58]" summary="false" /> <Sparkline data="[5, 8, 6, 12, 10, 15, 14, 18]" summary="false" /> </SparkGroup> ``` Pass `zero` when the group is bars or areas (so the shared domain anchors at zero), or an explicit `domain={[min, max]}` when you want a fixed frame instead of the data's own range (`domain` defaults to `"shared"`). Two details worth knowing. Only children that actually carry a `data` prop get the scale and size injected — plain wrappers, labels, and captions pass through untouched, so you can interleave them without them collecting stray DOM attributes. And the group renders one `<div className="mc-group">`, an `inline-flex` row that wraps: its gap is `--mc-gap` scaled by `--mc-density`, and `className`/`style` on `SparkGroup` land on that div if you want a different layout. ## Decorative vs. summarized — the `summary` decision [#decorative-vs-summarized--the-summary-decision] You'll notice `summary={false}` on nearly every demo above. That's a deliberate call, not a habit: * **Standalone chart** (the one thing in its region): keep the auto-summary on. It's the accessible name a screen reader announces — real, generated from the data. * **Repeated or captioned chart** (table rows, tabs, a chart next to a number that already states it): pass `summary={false}`. The surrounding text is the accessible name; a per-chart summary would just make a screen reader read the same thing many times. This is the only accessibility lever you routinely touch. Everything else — the `role="img"`, the `<title>`, and the whole interaction contract on interactive entries (roving arrow keys, select-to-pin with **Enter** or **Space**, touch scrub, live announcements) — is automatic. See [Accessibility](/docs/accessibility). # Design notes (/docs/design-notes) microcharts has opinions, and they're baked into the defaults so you rarely have to think about them. Here's the reasoning behind the ones that shaped the library, in case you're curious. ## Direct labels beat chrome [#direct-labels-beat-chrome] At this size, an axis, a legend, and a gridline all cost more ink than they return — so there are none. A value sits at the end of the line; a min and max mark themselves. The chart is almost all data, which is exactly what you want a reader to spend their attention on. ## Areas anchor at zero [#areas-anchor-at-zero] A filled Sparkline always measures from zero, because an area floating on an arbitrary baseline exaggerates change. Length should mean magnitude, honestly — the chart never says more than the numbers do. ## Color encodes, never decorates [#color-encodes-never-decorates] There's one accent per context, and a color change always means a change in meaning. Positive and negative come from a color-blind-safe pair, and they're always doubled by a glyph or a position, so the chart survives with no color at all. A preset can restyle a chart without ever changing what it says. ## Static first, interactivity opt-in [#static-first-interactivity-opt-in] Nearly every chart ships as two entries (WindBarb is static-only). The default is pure SVG — hook-free, listener-free, safe inside a React Server Component, and it renders to HTML with zero client JavaScript. Hover, roving keyboard focus, touch scrub, select-to-pin, and live announcements live in a separate `/interactive` subpath you import only where you need them. The line between the two is never blurred, so you never pay for interactivity you didn't ask for, and a static chart can never accidentally drag a listener into your server bundle. The interactive entry composes the static one rather than re-implementing it, so the interactive rendering can't drift from the static one. Every multi-unit chart resolves a gesture to a navigable *unit* through the same kernel — so interaction is one thing to learn across the catalog, not one dialect per chart. Single-unit charts have nothing to rove between and take `onSelect` alone. ## One grammar, not an options bag [#one-grammar-not-an-options-bag] `data` alone always renders something correct. A prop name means the same thing on every chart — `title`, `color`, `domain`, `format`, `summary` — so what you learn on one chart transfers to all of them. Variants are props; a genuinely different data shape is a different component rather than a deeper options object. Annotations — a threshold, a target zone, a marker — are children you nest, not configuration you pass. The result is an API you can mostly guess. ## Summaries are a feature, not an afterthought [#summaries-are-a-feature-not-an-afterthought] The natural-language sentence each chart generates from its data is the product, not a compliance checkbox. It's the accessible name a screen reader speaks, the text a crawler indexes, and the string a model can quote — one deterministic sentence doing all three jobs. It degrades honestly on empty, single, and flat data instead of describing a chart that isn't there. See [Accessibility](/docs/accessibility) for the details. ## Small is a material, not a limit [#small-is-a-material-not-a-limit] Composition, contrast, and the auto-summary all have to survive the smallest supported size. That constraint is what makes the charts calm: there's no room for anything that isn't carrying information, so nothing decorative gets in. ## Motion lives in the interactive build, not on every chart [#motion-lives-in-the-interactive-build-not-on-every-chart] Static charts have no `animate` prop and run no animation JavaScript — the one thing that moves inside a static host is `<Marker celebrate>`, a pure-CSS one-shot burst that reduced motion stills. Only the `/interactive` entries can play an entrance, and only when you opt in with `animate` (off by default). It runs through the Web Animations API, gated on `prefers-reduced-motion`. Every entrance follows the logic of the data it draws: a line draws left-to-right along its time axis, bars grow from the baseline, a donut fills clockwise from twelve o'clock, and labels arrive last — they annotate marks that already exist. Marks decelerate into place; they never bounce, loop, or draw the eye away from the data. Motion is a property of the interactive build, not a knob bolted onto the static one, so it can't leak into a server render or turn into decoration. ## Budgets are build gates [#budgets-are-build-gates] Size isn't an aspiration here — it's a CI gate. A chart that grows past its gzip budget fails the build, the same way a failing test does, and the SSR benchmark exits non-zero when a chart drops below its render floor. The numbers on the [Performance](/docs/performance) page are never hand-typed: the sizes are re-measured from the built `dist/` on every CI run, and the throughput figures are derived from the checked-in benchmark result, so a claim can't drift from what was measured. ## One package [#one-package] All the chart types ship from a single package, `@microcharts/react`, each behind its own subpath so you only bundle what you import. The catalog's collections — core, decision, expressive, frontier — are just metadata for browsing; they're never package or import boundaries. There's no plugin to install, no engine to configure. The root barrel (`@microcharts/react`, no subpath) carries only the shared pieces, so importing it pulls in no chart code: the `Chart` root wrapper every chart composes — a `role="img"` `<svg>` with the viewBox, `title`, and generated `summary` already wired, there if you ever need to build a custom mark — plus [`SparkGroup`](/docs/composition#small-multiples-one-shared-scale) for shared-scale small multiples, [`MicroProvider`](/docs/theming#a-component-api-if-you-prefer) for theming, and the `describeSeries` / `makeFormatter` / `EN` helpers documented under [Formatting](/docs/formatting) and [Accessibility](/docs/accessibility). ## The bar for a new chart type [#the-bar-for-a-new-chart-type] A new chart earns its place only if it clears a real bar: it reads at word size (roughly 200×60 px), it tells a data story the catalog can't already tell well, it has one honest primary encoding channel, and a first-time reader can read it back without training. "It looks cool" isn't a reason. This is why the catalog prefers uncommon *questions* over uncommon *shapes*. ## What we don't ship [#what-we-dont-ship] No pie, no needle gauge, no battery, no waffle, no violin, no 3-D, no gradients-as-decoration, no drop shadows on data, no looping animation. These aren't theme options you can switch on — they're designed out, because at a glance they mislead more than they inform. Where a rejected chart answered a real question, the catalog ships a faster replacement: [Bullet](/docs/charts/bullet) or [TapeGauge](/docs/charts/tape-gauge) instead of a speedometer, [SegmentedBar](/docs/charts/segmented-bar) for comparative part-to-whole, [MicroDonut](/docs/charts/micro-donut) as a capped icon-size mix when a glyph is specifically wanted, [MicroBox](/docs/charts/micro-box) instead of a violin. # Formatting & scale (/docs/formatting) Two orthogonal decisions live here: **how numbers are written** (`format` + `locale`) and **what range they're drawn against** (`domain`). Both are part of the one grammar — the same prop name means the same thing on every chart — and both are documented per chart, but this page is the whole story in one place, since it's easy to assume a default you didn't actually get. ## One formatter, three places [#one-formatter-three-places] A chart shows numbers in three spots: the **direct labels** it draws, the **accessible summary** a screen reader announces, and — on an interactive entry — the **readout** that follows the pointer. `format` feeds *all three* from a single definition — so a currency chart's spoken summary says "$1,240", not "1240". You never format the same number twice. `format` takes either **`Intl.NumberFormatOptions`** or a **plain function** `(n) => string`. Formatters are cached (`Intl.NumberFormat` construction is expensive), keyed by locale plus options, so hundreds of instances sharing one format shape build one formatter between them — never build your own `new Intl.NumberFormat` in a component. The cache is deliberately small: it holds 64 formatters and empties completely when it fills, on the reasoning that one app uses a handful of locale × option shapes, and a bounded cache that occasionally rebuilds beats one that grows forever. Need the same formatting *outside* a chart (a matching KPI label, a table cell)? Import the exported `makeFormatter` helper so your prose numbers line up with the chart's exactly, from the same cache: ```tsx import { makeFormatter } from "@microcharts/react"; const fmt = makeFormatter({ style: "currency", currency: "USD" }, "en-US"); fmt(42); // "$42.00" ``` The arguments are positional — `makeFormatter(format, locale, defaults?)`. The third argument is the fallback used when `format` is omitted; it's how a chart supplies its own default (see `Delta` below). ```tsx `"> <Sparkline data="[1240, 1310, 1290, 1420, 1380, 1510, 1470, 1600]" width="170" height="44" label="last" format="{ style: "currency", currency: "USD", maximumFractionDigits: 0 }" title="Revenue" /> ``` ## Percent, compact, decimals [#percent-compact-decimals] Anything `Intl.NumberFormat` supports works — percent, compact notation, fixed decimals, sign display. `Delta` even defaults to a locale-aware percent, so a raw ratio reads as a change with no config: ```tsx // → +12.8% <Delta value={4200} format={{ notation: "compact" }} /> // → +4.2K <Delta value={4200} format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }} />`" > <div className="flex flex-wrap items-center gap-6 text-lg"> <Delta value="0.128" summary="false" /> <Delta value="4200" format="{ notation: "compact" }" summary="false" /> <Delta value="4200" format="{ style: "currency", currency: "USD", maximumFractionDigits: 0 }" summary="false" /> </div> ``` ## A custom function [#a-custom-function] When `Intl` can't express the unit — milliseconds, "×" multipliers, a domain-specific symbol — pass a function. It receives the number and returns the exact string to render. The value is snapped to 12 significant digits before it reaches your function, so a number a chart derived internally (`value - target`) arrives as `-3.6`, not `-3.5999999999999943` — you write for clean data, not for IEEE arithmetic. ```tsx \`\${Math.round(n)} ms\`} />`"> <Sparkline data="[48, 45, 44, 40, 38, 36, 33, 31]" width="170" height="44" label="last" format="(n) => `${Math.round(n)} ms`" title="p95 latency" /> ``` ## The interactive readout [#the-interactive-readout] Import a chart from its `/interactive` subpath and it gains a readout: a small chip that follows the pointer, or the focused datum when you rove with the keyboard. It uses the same `format` and `locale` as everything else, so a currency chart's hover value matches its label and its summary exactly. **It is deliberately terse.** The chip names the datum and its value — a Funnel stage reads `Checkout 62% (1,240)`, a Slope line reads `Brazil: 44 → 28` — and nothing else. It does not repeat the axis names, the row label already printed beside it, or the grid position the cell already occupies. These are word-sized charts; a chip wider than the chart it annotates is worse than no chip. The fuller sentence still exists. Everything the chip leaves out — the comparison, the quadrant name, the running total, the per-cycle breakdown — is announced in the chart's live region, which is what a screen reader reads. So nothing is lost by the chip being short; it is a different audience, not less information. ```tsx import { Sparkline } from "@microcharts/react/sparkline/interactive"; // the readout, the endpoint label, and the spoken summary all read "$1,600" <Sparkline data={revenue} label="last" format={{ style: "currency", currency: "USD" }} />; ``` The chip is capped at `max(100%, 14em)` wide and ellipsizes past that, so a long formatted value cannot paint across the page. If you see an ellipsis, the value is too long for the chart — shorten it with `format` (`notation: "compact"` is usually the answer) rather than widening the chart. Its prose comes from `strings`, like every other word the library renders, so a localized bundle localizes the readout too. Its colors come from `--mc-surface`, `--mc-surface-ink` and `--mc-surface-edge`; see [Theming](/docs/theming#the-readout-surface). **Put the value somewhere else.** That same terse string is handed to you: every `onActive` / `onSelect` callback receives it as `datum.formatted`, formatted with the chart's own `format` and `locale`. So you can suppress the chip and render the value in your own layout — the pattern behind a KPI card whose big number tracks a sparkline you hover: ```tsx const [reading, setReading] = useState("$1,600"); // readout={false} keeps the crosshair, drops the chip; the value lands in your <output> <output>{reading}</output>; <Sparkline data={revenue} format={{ style: "currency", currency: "USD" }} readout={false} onActive={(d) => d && setReading(d.formatted!)} />; ``` `readout={false}` hides only the chip — hover, keyboard roving, touch scrub, the live-region announcements, and both callbacks all keep working. Leave `readout` at its default (`true`) and you get the chip and the callback both. ## Locale: separators, not language [#locale-separators-not-language] `locale` is a BCP-47 tag (`"de-DE"`, `"ja-JP"`, or an array of fallbacks). It controls how numbers and dates are *written* — the thousands separator, decimal mark, currency placement — matching the reader's conventions. ```tsx // 1,600 <Sparkline data={revenue} label="last" locale="de-DE" /> // 1.600`" > <div className="flex flex-wrap items-center gap-8"> <Sparkline data="[1240, 1310, 1290, 1420, 1380, 1510, 1470, 1600]" width="150" height="40" label="last" locale="en-US" title="US" /> <Sparkline data="[1240, 1310, 1290, 1420, 1380, 1510, 1470, 1600]" width="150" height="40" label="last" locale="de-DE" title="DE" /> </div> ``` > `locale` sets number/date **formatting**. It does not translate the summary *sentence* ("Trending up 200%…") — that's the `strings` contract on [Accessibility](/docs/accessibility#internationalization-and-rtl). Pick both for a fully localized chart: `locale` for the figures, translated `strings` for the prose. ### Server rendering: pass a `locale` explicitly [#server-rendering-pass-a-locale-explicitly] Omitting `locale` means `Intl` resolves the *runtime's* default — and on a server-rendered page that runtime is the server. Node typically resolves to the host's locale while the visitor's browser resolves to theirs, so the same chart can render `1,600` into the HTML and `1.600` after hydration. React reports that as a hydration mismatch, and the mismatched text is not patched up. This is not specific to microcharts — it is how `Intl` defaults work — but charts hit it more often than most UI, because the number reaches three places at once: the label, the accessible summary, and the readout. The fix is to make the choice explicit rather than ambient: ```tsx // Deterministic: the server and the browser format identically. <Sparkline data={revenue} label="last" locale="en-US" /> ``` Pass the locale your page has already resolved (from the request, a cookie, or your i18n provider) and use the same one on both sides. If a chart is client-only, the ambient default is fine. ## Scale: the `domain` decision [#scale-the-domain-decision] `domain` sets the value range the geometry is drawn against — the vertical frame. Omit it and the chart **auto-fits to its own data**. Pass `[min, max]` to pin a fixed frame instead — so a 40–60% reading looks like 40–60% of a 0–100 scale, not a full-height line. ```tsx // auto-fit — fills the height <Sparkline data={cpu} domain={[0, 100]} /> // fixed 0–100% frame`" > <div className="flex flex-wrap items-center gap-8"> <Sparkline data="[48, 52, 49, 55, 53, 58, 54, 60]" width="150" height="44" dots="minmax" title="Auto-fit" /> <Sparkline data="[48, 52, 49, 55, 53, 58, 54, 60]" width="150" height="44" domain="[0, 100]" dots="minmax" title="Fixed 0–100" summary="false" /> </div> ``` Auto-fit is not the same everywhere. Charts whose marks read as magnitude from a baseline — `Sparkbar`, `MiniBar`, `PairedBars`, and `Sparkline` once you turn on `fill` — anchor the auto-fitted domain at **zero**, because a bar cut off above zero lies about its own length. Line charts without a fill auto-fit to the data alone. Either way, a completely flat series is padded so it still has a band to sit in rather than collapsing to a degenerate scale. This is an **honesty decision**, not cosmetics: auto-fit maximizes detail for a single series, but a fixed domain is what makes two charts comparable. To share one scale across several charts at once, use `SparkGroup` — it reads every child's `data`, computes one union domain, and injects it into any child that didn't set its own (`zero` anchors that shared domain at zero). See [Composition](/docs/composition#small-multiples-one-shared-scale). ## Dates and times [#dates-and-times] On calendar and time charts, `format` still means what it means everywhere else: it formats the **numbers**. On `EventTimeline` that's a share, defaulting to a locale-aware percent. On `CalendarStrip` it's the day's value in the hover/focus readout — so it lives on the interactive entry only. The static `CalendarStrip` summary counts days — `Active 3 of 28 days over 4 weeks.` — and a count of days is not a number `format` gets to restyle. Date and time *strings* are a separate prop, **`dateFormat`**, taking `Intl.DateTimeFormatOptions` or a `(date) => string` function. It lives on the interactive entries (`@microcharts/react/calendar-strip/interactive`, `@microcharts/react/event-timeline/interactive`), which are the entries that render a spoken or hovered date at all — `locale` applies to it the same way. ```tsx import { CalendarStrip } from "@microcharts/react/calendar-strip/interactive"; <CalendarStrip data={days} dateFormat={{ month: "short", day: "numeric" }} locale="de-DE" />; ``` When you pass options (rather than a function), the formatter defaults to `timeZone: "UTC"`, so the same input renders identically in any host timezone — a chart never shifts a day because the viewer is in a different region. Your options spread after that default, so `{ timeZone: "America/New_York" }` overrides it deliberately. A `(date) => string` function bypasses the default entirely and owns its own timezone handling. # Full chart libraries (/docs/full-chart-libraries) [Recharts](https://recharts.org) and [Chart.js](https://www.chartjs.org) are full chart libraries. They draw surfaces that are mostly chart: scales, legends, tooltips, plugins, dashboard layouts. microcharts draws a word-sized mark *inside* a surface you already have — a sentence, a table cell, a KPI, a streamed reply — where a full chart library would be too heavy and too loud. We are not a substitute for either. Read [When to use microcharts](/docs/when-to-use) for the product decision; this page pins the size numbers so they stay honest. ## Side by side [#side-by-side] | | Full library (Recharts, Chart.js, …) | microcharts | | -------------------- | ------------------------------------ | ----------------------------------------------- | | Surface | The chart *is* the panel | The chart sits in prose / cell / KPI | | Chrome | Axes, legends, tooltips, brush | None by design | | Typical budget | Tens to hundreds of kB | <SizeMarketing /> | | Runtime dependencies | Real dependency trees | Zero (`dependencies: {}`; React is a peer) | | Server Components | Usually a client chart runtime | Default export is hook-free SVG, zero client JS | | Accessible name | You wire it (plugins, tables, aria) | `role="img"` + summary from the data by default | A product can use both when it needs both jobs. ## Recharts [#recharts] Recharts is a strong default for React dashboards: composable `<LineChart>`, axes, tooltip, responsive container. Orientation numbers (not “smaller wins for every app”): <VsRechartsTable /> **Reach for Recharts** when the page is mostly chart — ticks, legends, brush, or a familiar Recharts tree. **Reach for microcharts** when the mark must live in a sentence, a cell, or an RSC with nothing to hydrate. ```tsx // Recharts — full surface import { LineChart, Line, XAxis, YAxis, Tooltip, ResponsiveContainer } from "recharts"; <ResponsiveContainer width="100%" height={240}> <LineChart data={rows}> <XAxis dataKey="t" /> <YAxis /> <Tooltip /> <Line type="monotone" dataKey="v" /> </LineChart> </ResponsiveContainer>; // microcharts — word-sized mark import { Sparkline } from "@microcharts/react/sparkline"; <span className="mc-inline"> <Sparkline data={[3, 5, 4, 8, 6, 9]} dots="none" summary={false} width={64} height={16} /> </span>; ``` ## Chart.js [#chartjs] Chart.js is Canvas-first, with a large plugin and config ecosystem. In React it is usually wrapped by `react-chartjs-2`. That stack is for dashboard and report canvases — not for a mark in a table cell. <VsChartJsTable /> **Reach for Chart.js** when you need Canvas, existing Chart.js configs or plugins, or dense series on a chart panel. **Reach for microcharts** when you need inline SVG, accessible-by-default summaries, or static RSC output. Canvas charts need an explicit accessibility path (hidden table, aria, plugins). microcharts makes the accessible name the default — see [Accessibility](/docs/accessibility). That is not a claim that Chart.js cannot be made accessible. ## What this page is not saying [#what-this-page-is-not-saying] * Not “faster than Recharts for dashboards” * Not “Chart.js, but lighter, for the same job” * Gzip figures here are orientation, not a scoreboard If the job is a full chart, pick a full library. If the job is a word-sized mark, pick microcharts — or add it alongside the library you already trust. ## Next [#next] * [When to use microcharts](/docs/when-to-use) * [microcharts vs Recharts](/docs/vs-recharts) · [microcharts vs Chart.js](/docs/vs-chartjs) — the per-library detail * [React sparklines](/docs/react-sparklines) * [Inline charts](/docs/inline-charts) * [Performance](/docs/performance) * [Introduction](/docs) # Introduction (/docs) microcharts is a set of tiny, handcrafted charts for React — **made for AI first, and for the people reading what it writes**. The grammar is small and predictable enough for a model to emit correctly mid-sentence, and every chart describes itself in words, so a chart an LLM streams into a chat reply, a document, or a generated slide is one a person can read and trust. They're built to sit *inside* an interface — in a sentence, a table cell, a KPI card, a tab header, a streamed reply — where a full chart library would be too heavy and too loud. One quiet signal, read at a glance. Prefer [Set up with AI](/docs/quickstart#set-up-with-an-ai-agent) — paste one prompt and an agent installs the package, imports the stylesheet, and verifies with a first chart. Or install manually (both steps are required): The other half of manual setup is one stylesheet import at your app root — see the [Quickstart](/docs/quickstart#set-up-manually). Every chart renders from `data` alone, ships as pure SVG with **zero runtime dependencies**, and carries an accessible description generated from the data itself — the same properties that make it safe for a model to write are the ones that make it pleasant for a human to use. ```tsx `" > <Sparkline data="[3, 5, 4, 8, 6, 9]" width="120" height="32" title="Weekly revenue" /> ``` ## Why microcharts [#why-microcharts] * **AI-native, by design.** A chart is plain `data` plus generated words, so a model can emit one mid-sentence and read one back — [chat streams, agents, and tool output](/docs/ai) are the primary homes, not an afterthought. One grammar across 106 types means an LLM that has seen one chart can write them all. * **Zero dependencies.** No chart engine, no D3 — just SVG. CI-enforced, forever. * **Server-component safe.** Static charts are hook-free and listener-free; they render to HTML with zero client JavaScript, and add interactivity only from a separate `/interactive` subpath — where one contract covers the catalog: hover, roving arrow keys, touch scrub, and click-to-pin, read back through `onActive` / `onSelect`. Single-unit charts have nothing to rove between and take `onSelect` alone. * **Accessible by default.** Each chart is an `img` with a natural-language summary built from your data — nothing to remember, nothing to drift. * **Tiny.** **\~2–7 kB interactive · \~1–4 kB static** gzip each, imported from their own subpath and budget-gated in CI. ## One catalog, one grammar [#one-catalog-one-grammar] The library ships a full catalog of chart types, grouped by the question each one answers. `data` alone always renders something correct, and a prop name means the same thing on every chart — so you pick by the *decision* you need read, not by fighting an options bag. From sparklines to bump charts, funnels, honeycombs, and calendar strips — a small sample of what ships: A representative slice of the catalog spans trends, comparisons, distributions, and status — see every chart type at [/docs/charts](/docs/charts). Browse them all on the [All charts](/docs/charts) page, which files every type under the question it answers — start from what you need someone to see, and land on the chart. ## Where they live [#where-they-live] The point of a word-sized chart is that it belongs *in* your interface, not in a dashboard off to the side. And because it's plain SVG that renders from `data` alone, "interface" isn't limited to a browser tab: * **In your product** — a trend in a table cell, a KPI card, a tab header, a dense dashboard, where a full chart engine would be too heavy and too loud. * **In a report or slide** — a figure in a rendered PDF or deck, the same markup that drops into a table cell, with nothing to export. * **In your docs** — inline in Markdown, next to the sentence that explains it. The charts on this very page are rendered exactly that way — MDX in, live SVG out. * **In an AI reply** — streamed mid-sentence by a model, since every chart is plain data plus generated words. [AI-native](/docs/ai) shows a live stream doing exactly that. Here's the same chart doing its job in four of those homes: [Composition](/docs/composition) has the exact placement recipe for each surface — a table cell, a KPI card, a tab, or inline in a sentence. Unsure whether this library or a full chart library fits? [When to use microcharts](/docs/when-to-use). Ready to render one? The [Quickstart](/docs/quickstart) gets you from install to a live chart in minutes. ## FAQ [#faq] ### What are micro charts? [#what-are-micro-charts] Micro charts — also called sparklines, tiny charts, or inline charts — are small, word-sized data visualizations: a trend line, bar, or dot that fits inside a sentence, table cell, or KPI card without axes or legends. They answer one question at a glance in the space of a word, where a full chart would be too heavy and too loud. ### What is microcharts? [#what-is-microcharts] microcharts is a React chart library of word-sized SVG charts — sparklines, bars, bullets, and the rest of the catalog — built to sit inside sentences, table cells, KPI cards, and AI replies. Zero runtime dependencies, accessible by default, and server-component safe. ### How is microcharts different from Recharts or Chart.js? [#how-is-microcharts-different-from-recharts-or-chartjs] Those are full chart libraries for surfaces that are mostly chart. microcharts is built to sit *inside* an interface — word-sized SVG marks where a full chart library would be too heavy and too loud. One chart per subpath, typically **\~2–7 kB interactive · \~1–4 kB static** gzip, no axes or legends, static entries with **zero client JavaScript** from an RSC. We are not a replacement; see [When to use](/docs/when-to-use) and [Full chart libraries](/docs/full-chart-libraries), or the measured per-library pages: [vs Recharts](/docs/vs-recharts), [vs Chart.js](/docs/vs-chartjs), [vs react-sparklines](/docs/vs-react-sparklines), [vs MUI X Sparkline](/docs/vs-mui-x-sparkline), and [vs visx](/docs/vs-visx). ### Are microcharts accessible? [#are-microcharts-accessible] Yes. Every chart is `role="img"` with a natural-language summary generated from the data. Interactive entries add keyboard navigation and a polite live region. Direction and state are never color-alone — see [Accessibility](/docs/accessibility). ### Do static microcharts need client JavaScript? [#do-static-microcharts-need-client-javascript] No. Default exports are hook-free pure SVG — RSC-safe with zero client JS. Import the matching `/interactive` subpath only when you need hover, keyboard, touch, or selection. ### Why is there no pie chart, gauge, or waffle? [#why-is-there-no-pie-chart-gauge-or-waffle] They fail at word size: pie angles are unreadable in a table cell, a needle gauge spends its pixels on chrome, a waffle doesn't fit in a word. Each refusal has an honest in-catalog replacement — [SegmentedBar](/docs/charts/segmented-bar) for pie, [Bullet](/docs/charts/bullet) for gauges, [IconArray](/docs/charts/icon-array) for waffle. The reasoning lives in [Design notes](/docs/design-notes) and [When to use](/docs/when-to-use). ### Why does my first chart render unstyled, or with serif labels? [#why-does-my-first-chart-render-unstyled-or-with-serif-labels] Almost always one of two setup steps: the stylesheet isn't imported at your app root (`import "@microcharts/react/styles.css"`, once), or the surrounding page never sets a `font-family`, so SVG text falls back to a serif — set `--mc-font` or give the page a font. Both are covered in the [Quickstart](/docs/quickstart#set-up-manually). ### Can I match the charts to my brand color? [#can-i-match-the-charts-to-my-brand-color] Yes — pass one accent to `defineTheme` and it derives a color-blind-safe categorical palette plus hand-tuned-style dark twins, in OKLCH, with zero dependencies; or set the `--mc-*` tokens directly. The one thing a theme can never change is what the data means: positive and negative keep their hues on every accent and preset. See [Theming](/docs/theming). ### How do I propose a new chart type? [#how-do-i-propose-a-new-chart-type] Open an issue first. A new type must clear the admission bar: a unique data story the catalog can't already answer, one honest encoding channel, and readable at ≤ 200×60 px without training. It's a high bar on purpose — every shipped chart clears it, and [CONTRIBUTING.md](https://github.com/ganapativs/microcharts/blob/main/CONTRIBUTING.md) walks through the rest. > microcharts is tested and ready to use in production — but it hasn't been battle-tested across every stack and edge yet, so you may hit the occasional rough edge. When you do, tell us: bug reports and feature requests on [GitHub](https://github.com/ganapativs/microcharts/issues) are how it keeps getting sharper. ## Made by [#made-by] microcharts is designed and built by [Ganapati V S](https://meetguns.com) — [@ganapativs](https://x.com/ganapativs) on X, [ganapativs](https://github.com/ganapativs) on GitHub. It's free and open source under the MIT license; the code lives on [GitHub](https://github.com/ganapativs/microcharts), where issues, ideas, and stars are all welcome. Want to contribute? [CONTRIBUTING.md](https://github.com/ganapativs/microcharts/blob/main/CONTRIBUTING.md) covers the dev setup, the non-negotiables, and what a PR needs to ship. # Inline charts (/docs/inline-charts) Word-sized charts sit *inside* the interface you already ship: a trend in a table cell, a sparkline after a number, a bullet in a KPI, a mark in a streamed reply — not a chart page you navigate to. That is what `@microcharts/react` is built for. Full dashboard canvases belong with [full chart libraries](/docs/full-chart-libraries). <CatalogTotal /> types, one grammar. Size band: <SizeMarketing />. Static entries ship **zero client JavaScript** from a React Server Component. Accessible by default — each chart is an `img` with a summary generated from the data. ## The surfaces [#the-surfaces] ### In a sentence [#in-a-sentence] Wrap with `mc-inline`, drop endpoint dots, mark decorative when the sentence already carries the meaning: ```tsx p95 latency this week{" "} <span className="mc-inline"> <Sparkline data={latency} dots="none" summary={false} width={64} height={16} /> </span>{" "} — trending down. </p>`" > <p className="max-w-md text-[0.95rem] leading-relaxed"> {"p95 latency this week "} <span className="mc-inline"> <Sparkline data="[48, 45, 44, 40, 38, 36, 33, 31]" dots="none" summary="false" width="64" height="16" /> </span> {" — trending down."} </p> ``` ### In a table cell [#in-a-table-cell] ```tsx <table className="w-full max-w-sm text-sm tabular-nums"> <thead className="sr-only"> <tr> <th scope="col"> Service </th> <th scope="col"> Trend </th> <th scope="col"> Now </th> </tr> </thead> <tbody> <tr className="border-b border-hairline"> <td className="py-1.5 pr-3 text-fd-muted-foreground"> checkout </td> <td className="py-1.5"> <Sparkline data="[40, 38, 36, 34, 32, 31, 30, 31]" width="72" height="16" dots="none" summary="false" /> </td> <td className="py-1.5 pl-3 text-right"> 31ms </td> </tr> <tr> <td className="py-1.5 pr-3 text-fd-muted-foreground"> search </td> <td className="py-1.5"> <Sparkline data="[80, 78, 82, 79, 81, 80, 79, 78]" width="72" height="16" dots="none" summary="false" /> </td> <td className="py-1.5 pl-3 text-right"> 78ms </td> </tr> </tbody> </table> ``` ### In a KPI / tab [#in-a-kpi--tab] Attainment and cadence marks stay tiny on purpose — [Bullet](/docs/charts/bullet), [Progress](/docs/charts/progress), [Delta](/docs/charts/delta), [StatusDot](/docs/charts/status-dot). Exact placement recipes: [Composition](/docs/composition). Broader fit: [When to use microcharts](/docs/when-to-use). ## Server-component safe [#server-component-safe] Static charts are hook-free and listener-free — they render to HTML with zero client JavaScript. Add interactivity only from a separate `/interactive` subpath. ```tsx // Server Component — no "use client", nothing to hydrate for the chart import { Sparkline } from "@microcharts/react/sparkline"; export default function Row() { return <Sparkline data={[3, 5, 4, 8, 6, 9]} title="Weekly revenue" />; } ``` ## Start here [#start-here] * [When to use microcharts](/docs/when-to-use) * [React sparklines](/docs/react-sparklines) * [Introduction](/docs) — grammar and catalog * [Quickstart](/docs/quickstart) # Performance (/docs/performance) Performance isn't a marketing line here — it's a build gate. Every figure on this page is produced by a command you can run yourself, checked against the shipped `dist` in CI, and regenerated on every release so it can never drift from reality. ## Size [#size] Each chart is imported from its own subpath, so a bundle ships only the charts it uses — importing `Sparkline` never pulls in the other 105. Sizes are gzip, measured by `pnpm size` and gated: a chart that grows past its budget fails the build. The interactive catalog lands between **1.88 kB and 6.64 kB** gzip, with a **median of 5.03 kB** — hover, roving keyboard focus, select-to-pin, touch scrub, and live announcements from the `/interactive` subpath. The static twin lands between **0.97 kB and 3.99 kB**, with a **median of 2.6 kB** — pure SVG, zero client JavaScript. A page pays for interactivity only where it actually uses it. About 0.5 kB of the interactive delta is the shared picker kernel, which the per-subpath gate measures standalone in every entry; a page using several interactive charts bundles it once. Twenty-five charts sit above the 3 kB static reference line, none of them by more than 0.99 kB. Sparkline, the most configurable primitive in the set, is the largest; most of the rest are value-series charts that host annotations (ChangePoint, WinProbWorm, ForecastCone, DualSparkline, BurnChart, SpreadBand, RetentionCurve, ControlStrip, QueueDepth, SparkBar, EnsembleGhosts, NetFlow, Slope), plus Station Glyph, PercentileLadder, ShiftHistogram, StackedArea, ABStrips, PolarClock, Constellation, Dumbbell, CyclePlot, Waterfall, and TapeGauge. The annotation hosts carry a small shared walker that resolves `Threshold`, `Marker`, and the rest against the chart's scale — you pay for it only on those charts, and each is still smaller than a single icon font. ### Splitting the stylesheet [#splitting-the-stylesheet] `@microcharts/react/styles.css` is one artifact for the whole catalog, and importing it once is the right default — it is small, it caches, and it never grows with the number of charts you use. If you ship exactly one or two charts and want the rules for the rest gone, there is an opt-in split: `@microcharts/react/styles/core.css` carries everything shared, and `@microcharts/react/styles/<slug>.css` carries the rules specific to a single chart. Only the charts with chart-specific CSS have a file; the rest need `core.css` alone. ```ts import "@microcharts/react/styles/core.css"; import "@microcharts/react/styles/sparkline.css"; ``` `core.css` plus the slugs you import is equivalent to the matching subset of `styles.css` — same rules, same `@layer` membership, same cascade order — so the split is a byte trade, never a behavior change. Import one or the other, not both. ## Server rendering [#server-rendering] Static charts are hook-free and listener-free, so a React Server Component renders them to plain SVG on the server — **zero client JavaScript** reaches the browser. Throughput, measured by `pnpm bench` rendering *N* sparklines to an SVG string: A table of **500 sparklines becomes HTML in under six milliseconds**, streams as part of the document, and ships nothing to hydrate. Across all 106 chart types the median **static** SSR render is about **0.03 ms per chart** — the heavier expressive and frontier instruments cost more geometry, the simple strips cost almost nothing. The core summary kernel is just as cheap: `describeSeries`, which writes every chart's accessible sentence, runs at roughly **892,000 calls per second** (24-point series, measured by `pnpm bench`), so accessibility is never the thing that slows a render down. ## Why it's fast [#why-its-fast] The speed isn't a trick — it's the absence of one. * **No chart engine.** No D3, no layout runtime, no virtual DOM diff for a static chart. Scales, paths, and stats are a few hundred lines of pure functions, and the output is a handful of SVG nodes — typically six or fewer per chart. * **Zero runtime dependencies.** `dependencies: {}`, enforced by CI, forever. Nothing to resolve, nothing to audit, nothing to bloat a lockfile. * **Integer geometry, crisp marks.** Coordinates are rounded at generation and rectilinear marks use `shape-rendering: crispEdges`, so the browser does less work rasterising them. * **One stylesheet, one cascade layer.** Theming is CSS custom properties in a low-specificity `@layer`, not inline styles recomputed per instance. * **A scrub costs one render per unit crossed, not one per pointer move.** Interactive entries put a single listener on the wrapper and resolve the unit with pure math, then bail out when the unit hasn't changed — so a sweep across a 24-point Sparkline re-renders at most 24 times no matter how many pointer events the browser delivers. ### Re-rendering many charts [#re-rendering-many-charts] Static entries are hook-free — that's what keeps them RSC-safe — so they can't memoise internally: a parent re-render re-runs each chart's geometry. That's cheap per chart, but it adds up in a table of hundreds. If you render many charts inside a component that re-renders for unrelated reasons, wrap them and keep `data` referentially stable: ```tsx const Spark = memo(Sparkline); ``` The catch is that `memo` only helps when props are actually stable — pass a fresh array literal (`data={[1, 2, 3]}`) or JSX children and it misses every time, and you pay the comparison on top of the render you were going to do anyway. Hoist the array, or skip it. We don't ship `memo` on the charts themselves for exactly that reason: it would tax the common case to speed up a specific one, and it's your call, not ours. ## Honest caveats [#honest-caveats] * **The bench is one process, and that used to bite.** Measuring 106 components in sequence let earlier charts leave the later ones cold, and a median over windows short enough for one GC pause produced bimodal numbers — the same chart read 140 and 35 rows/ms on consecutive runs of identical code. `pnpm bench` now warms each component immediately before timing it and reports the fastest window, since GC and scheduler noise only ever slow a window down. Every chart clears its floor; if one stops, `pnpm bench` exits non-zero and names it. * **Interactive entries do ship JavaScript.** The `/interactive` subpath adds a client component and a small set of listeners on the wrapper — pointer, keyboard, and touch — plus the shared picker kernel that resolves them to a unit with pure math. There is still never a listener per data point, so a 30-point chart and a 365-cell grid cost the same. It's tiny, but it isn't zero — reach for the static entry unless a chart genuinely needs hover, keyboard, selection, or live announcements. * **These numbers are one machine, one Node.** They measure *relative* cost honestly and reproduce on your hardware; treat them as a floor to reproduce, not an absolute to quote. ## Reproduce it [#reproduce-it] Every figure above regenerates from the repo. Nothing is hand-keyed — the docs read the measured output directly. ```bash git clone https://github.com/ganapativs/microcharts pnpm install pnpm build # build dist the numbers are measured against pnpm bench && node scripts/sync-bench.mjs # SSR throughput → bench-summary.json node scripts/sync-sizes.mjs # gzip budgets → chart-sizes.json ``` CI runs `--check` on both synced files, so a stale number fails the build the same way a failing test does. # Quickstart (/docs/quickstart) ## Set up [#set-up] Prefer an agent — paste the prompt once. It installs the package, imports the stylesheet at your app root, records the conventions in your agent-rules file, and verifies with a first chart. Or do the two steps yourself under [Set up manually](#set-up-manually). ### Set up with an AI agent [#set-up-with-an-ai-agent] Hand the prompt below to your coding agent — **Cursor, Claude Code, GitHub Copilot, Codex**, or any model, large or small. Works on a fresh repo or an existing one. It's also served verbatim at [`/agent-setup.md`](/agent-setup.md). <div className="agent-prompt"> ```md title="Paste into your agent" Set up **@microcharts/react** in this repo — word-sized, zero-dependency React charts (React 18 or 19 peer, ESM-only). Complete every step in order; don't stop to ask. ## 1 · Install - If this repo is not already a React 18/19 app, scaffold one first (Vite `react-ts` or Next.js), then continue. - Install `@microcharts/react` with this repo's package manager. - Import the stylesheet once at the app root (both package + stylesheet are required): - Next.js App Router: `app/layout.tsx` - Next.js Pages Router: `pages/_app.tsx` - Vite / other React apps: the entry file (e.g. `src/main.tsx`) `import "@microcharts/react/styles.css"` - Charts inherit the page font. If labels look like a serif fallback, set `:root { --mc-font: system-ui, sans-serif; }`. ## 2 · Docs — fetch small, on demand - https://microcharts.dev/llms.txt — index: every chart + guide links. Read this now. - https://microcharts.dev/catalog.json — full API. Do **not** read the whole file. Find the chart by `slug`, then use `sharedProps` + that chart's `props`. If the chart has `sharedInteractive` / the document has `howToRead`, follow those; otherwise use the chart's `.md` for interactive callbacks. Never invent props. - https://microcharts.dev/docs/charts/<slug>.md — one chart's page (import path, edge cases). Fetch only for charts you use — pick the slug from the index. - https://microcharts.dev/docs/quickstart.md — grammar + interactive contract, if you need more than the rules below. If you can't fetch URLs, skip this step — the rules below are enough to render a first chart correctly. ## 3 · Record the conventions Append the rules below as a `## microcharts` section in `AGENTS.md` (create the file if missing — Cursor, Copilot, and Codex read it). If this repo uses Claude Code, mirror it: `ln -s AGENTS.md CLAUDE.md` on macOS/Linux, or copy the section into `CLAUDE.md` on Windows. - One chart = one subpath import, e.g. `import { Sparkline } from "@microcharts/react/sparkline"`. The default export is static — RSC-safe, zero client JS. Add `/interactive` only when hover, keyboard, touch, or selection is needed. That entry is a client component: in Next.js App Router, import it from a `"use client"` file. WindBarb is static-only. - `data` alone always renders; single-value charts take `value` instead. Shared prop names mean the same thing everywhere — see `sharedProps` in `/catalog.json`. Chart-specific props and callbacks live on the chart's catalog entry and its `.md` page; don't memorize them. - Interactive entries share one contract: hover/arrows activate; click/tap/Enter/Space select; Escape clears. Prefer each chart's `sharedInteractive` list when present (lean scalars may take only `onSelect`; MinimapStrip uses `onWindowChange` in chart `props`). For entrance motion: pass `animate` and import `@microcharts/react/motion` once on the client. - `null`, `NaN`, or non-finite values in `data` are gaps, never zeros. - Accessibility is automatic (`role="img"` + a generated summary). Inline in a sentence: wrap in `<span className="mc-inline">` and pass `summary={false}`. - Theme with `--mc-*` or `data-mc-theme` (omit for default), or `defineTheme` from `@microcharts/react/theme`. Charts paint no background. Prefer tokens; `color` / categorical `colors[]` are valid when the chart's docs say so. - Annotations are children: `Threshold`, `TargetZone`, `Marker`, `Callout` from `@microcharts/react/annotations`. - Never add another charting dependency. No pie or gauge — use `Bullet`, `SegmentedBar`, or `MicroDonut`. ## 4 · Verify Render `<Sparkline data={[3, 5, 4, 8, 6, 9]} title="Weekly revenue" />` in a real page, then run the dev server or build. Self-check: - Chart missing or unstyled → the styles.css import isn't at the root (step 1). - Labels render in a serif font → set `--mc-font` (step 1). Finish with a short report: the installed version, the file importing styles.css, the file holding the conventions, and the page rendering the test chart. ``` <AgentPromptCopy /> </div> The prompt fetches small, targeted files — the [`/llms.txt`](/llms.txt) index first, then one chart's `.md` page at a time — so it stays inside the context window of smaller models and works from today's real API instead of a memorized guess. The rules are inlined too, so it still works when the agent can't reach the network. ### Set up manually [#set-up-manually] Two steps, once, at your app root — package plus stylesheet. Both are required, and both fit in the next minute. **1 · Install.** React 18 or 19 is a peer dependency; there are no other runtime dependencies. **2 · Import the stylesheet once** at the root of your app — it carries every theming token and chart style in a low-specificity cascade layer, so your own styles always win. Where "root" means depends on your framework — anywhere that runs once, before any chart renders: #### Next.js ```tsx title="app/layout.tsx" import "@microcharts/react/styles.css"; ``` #### Vite / CRA / other React apps ```tsx title="src/main.tsx" import "@microcharts/react/styles.css"; ``` > Charts **inherit your page's font**. If the surrounding page never sets a `font-family` (some minimal starters and sandboxes don't), SVG text falls back to a serif and labels look wrong — give your page a font, or set one just for charts: ```css :root { --mc-font: system-ui, sans-serif; } ``` Full detail — why it inherits, and per-scope fonting — in [Theming](/docs/theming#the-font). ## Your first chart [#your-first-chart] Every series chart renders from `data` alone — single-value charts take `value`. Either way it works in a React Server Component with **zero client JavaScript** — it's pure SVG, and its accessible name is generated from the data. ```tsx ; }`" > <Sparkline data="[3, 5, 4, 8, 6, 9]" width="120" height="32" title="Weekly revenue" /> ``` ### Try it live [#try-it-live] No install needed to feel it out. Open a full Vite + React app with the package installed in StackBlitz — static and interactive charts, inline and block, four themes, running in your browser. <StackBlitzSandbox /> ## The shared grammar [#the-shared-grammar] One idea runs through the whole catalog: **the same prop name means the same thing on every chart.** Learn these once and they transfer everywhere — a new chart type is a new data shape, never a new vocabulary. The data prop alone always renders something correct; everything else is opt-in. | Prop | Type | What it does | | ---------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `data` | `(number \| null)[] \| per-chart shape` | The series. `null` / `NaN` are gaps, never zeros. The one required prop; each chart documents its own shape when it isn't a plain number array. | | `domain` | `[min, max]` | Fix the value range instead of auto-fitting — see [Formatting & scale](/docs/formatting#scale-the-domain-decision). | | `color` | `string` | Mark color: any CSS color or a token (`"var(--mc-accent)"`). Semantic tokens keep their meaning — see [Theming](/docs/theming). | | `title` | `string` | Names the chart — an SVG `<title>`, so it becomes the accessible name and the hover tooltip, not visible text. | | `summary` | `string \| false` | Override the auto-generated accessible sentence, or pass `false` to mark the chart decorative — see [Accessibility](/docs/accessibility). | | `format` | `Intl.NumberFormatOptions \| (n) => string` | How numbers render in labels and summaries — see [Formatting & scale](/docs/formatting). | | `positive` | `"up" \| "down"` | Which direction is good, so color and arrows point the honest way (lower latency is `"down"`). | | `label` | *per chart* | A short direct label next to the mark, in a reserved gutter — never an axis or legend. | | `dots` | *per chart* | Which individual points to emphasize (e.g. `"minmax"` on a line). | Not every prop applies to every chart — a bar chart has no `dots`, and the single-value charts take `value` rather than `data` — but wherever a concept exists, its prop name and meaning are always these. Each one has a deeper home: [Formatting & scale](/docs/formatting) owns `format` and `domain`, [Theming](/docs/theming) owns `color`, and [Accessibility](/docs/accessibility) owns `summary`. Alongside the grammar sit the layout props — `className` and `style` on every chart, plus `width` and `height` on the charts whose geometry is sized that way (the fixed-glyph ones size from `style` or their own `size` / `cell` knob) and `id`, which opts into `<title>`/`<desc>` + `aria-labelledby` naming; see [Sizing](/docs/sizing). The i18n props are `locale` (BCP-47, for number and date formatting) and `strings` (the summary/label templates), plus `seriesStrings` on the multi-series charts — see [Accessibility](/docs/accessibility#internationalization-and-rtl). Everything else is specific to a chart's own shape and listed in the prop table on its page. To place charts in real UI — or render several on one shared scale with `SparkGroup` — see [Composition](/docs/composition). Annotations are children: [`Threshold`, `TargetZone`, `Marker`, `Callout`](/docs/annotations). ## Add interactivity [#add-interactivity] Need hover, keyboard navigation, touch, or live announcements? Import the same chart from its `/interactive` entry. The rendered output and the accessible name are identical — the interactive entry composes its static twin rather than re-implementing it — and it **adds** props rather than changing any: the interaction callbacks below, plus `animate`, `strings` on the charts whose static entry doesn't take it, `live` on the single-value charts, and `onWindowChange` on MinimapStrip. The interactive entry **is** a client component: in a Next.js App Router page, render it from a file with `"use client"` at the top (or anywhere inside one). ```tsx "use client"; import { Sparkline } from "@microcharts/react/sparkline/interactive"; <Sparkline data={[3, 5, 4, 8, 6, 9]} title="Weekly revenue" />; ``` ### One interaction contract [#one-interaction-contract] Every interactive chart behaves the same way, so you learn it once. Hover or arrow keys make a unit **active**; a click, tap, **Enter**, or **Space** **selects** it and pins the readout so it survives blur. **Escape** clears, **Home**/**End** jump to the ends, and arrows rove in both axes (←/↑ previous, →/↓ next). On touch, a tap pins and a drag scrubs. What a "unit" is depends on the chart — a point, a bar, a day cell, a segment — and each chart's page names its own. | Prop | Type | What it does | | ---------------------- | ------------------------------------- | ------------------------------------------------------------------------------------ | | `onActive` | `(datum: MicroDatum \| null) => void` | The active unit changed (pointer or keyboard). `null` when the chart clears. | | `onSelect` | `(datum: MicroDatum \| null) => void` | A unit was selected or unselected — click, tap, `Enter`, `Space`, `Escape`. | | `selectedIndex` | `number \| null` | Control the selection yourself. | | `defaultSelectedIndex` | `number \| null` | Seed the selection once, then let the chart own it. | | `readout` | `boolean` | Show the floating value chip on hover (default `true`). `false` hides only the chip. | `MicroDatum` is `{ index, value, label?, formatted? }`. Two of the fields carry the value in different forms, so you pick the one that fits: **`value`** is the raw primary number — compute with it (`null` when the unit encodes nothing); **`formatted`** is the ready-to-display string the chart's own readout would show, built with your `format`/`locale` — render it. For a plain chart that's just the value (`"$0.53"`); for a two-part unit it's the whole readout (`"48 → 68 (up 42%)"`). `index` identifies the unit (point, bar, cell, segment…), and `label` is its human name where one exists (`"Berlin"`, `"Checkout"`). Same shape on every chart and both callbacks. Pair the two to lift the value out of the chart. Set `readout={false}` to keep the hover crosshair but suppress the in-chart chip, and read `datum.formatted` in `onActive` to render that value wherever you like — a KPI number, a sentence, a table cell — without re-deriving `format`/`locale` yourself: ```tsx const [spend, setSpend] = useState("$0.53"); <Sparkline data={cost} format="$,.2f" readout={false} onActive={(d) => d && setSpend(d.formatted!)} />; ``` Scalar charts with a single unit — Delta, Progress, StatusDot, Bullet and the rest — take `onSelect` only; there's nothing to rove between. Fifteen of them also take `live` (default `true`): as the value updates, the new reading is announced through a polite live region, throttled so a streaming number never spams a screen reader. Not all of them do — Bullet's only interaction prop is `onSelect` — so check the chart's own page. Two charts opt out of the picker on purpose: `MinimapStrip` is a range slider with its own `onWindowChange([lo, hi])`, and `TokenConfidence` moves real focus through inline text spans. Full detail, including the live-region behavior, is on [Accessibility](/docs/accessibility#one-interaction-contract). ## Animate on mount (optional) [#animate-on-mount-optional] Interactive entries also take an `animate` prop — the chart draws on instead of appearing instantly. It's off by default, and inert on the server and on hydrated server HTML, so it never fights SSR or flashes over painted content; a fresh client-side mount is what plays it. Wire the engine once, client-side, then opt in per chart: ```tsx "use client"; import "@microcharts/react/motion"; // once, client-side import { Sparkline } from "@microcharts/react/sparkline/interactive"; <Sparkline data={[3, 5, 4, 8, 6, 9]} title="Weekly revenue" animate />; ``` `prefers-reduced-motion` wins unconditionally — a reader who asked for less motion gets the finished chart, never the entrance. ## Import paths [#import-paths] Import each chart from its own subpath so you only ship what you use. Nearly every chart follows the same two-entry pattern — a static default and an `/interactive` twin (WindBarb is the lone static-only exception): | Chart | Static | Interactive | | ------------ | ---------------------------------- | ---------------------------------------------- | | Sparkline | `@microcharts/react/sparkline` | `@microcharts/react/sparkline/interactive` | | SparkBar | `@microcharts/react/sparkbar` | `@microcharts/react/sparkbar/interactive` | | Delta | `@microcharts/react/delta` | `@microcharts/react/delta/interactive` | | Bullet | `@microcharts/react/bullet` | `@microcharts/react/bullet/interactive` | | ActivityGrid | `@microcharts/react/activity-grid` | `@microcharts/react/activity-grid/interactive` | Every other chart uses the same shape (WindBarb ships static-only, with no `/interactive` twin) — see [All charts](/docs/charts) for the full catalog, each page listing its own import path and props. ## Compatibility [#compatibility] * **React 18 or 19** as a peer dependency — no other runtime dependencies, ever (`dependencies: {}`, CI-enforced). * **ESM-only.** The package ships `"type": "module"`; there's no CommonJS build. * **Server-component and SSR-safe.** Static entries are hook-free and listener-free, so they render to plain SVG on the server with zero client JavaScript — no `"use client"` needed unless you import from `/interactive`. * **Browser floor: evergreen, ES2022.** That includes Safari from version 16.4 — a couple of ES2022 array methods used internally crash on older Safari, so that's the practical minimum, not just a `tsconfig` setting. # React sparklines (/docs/react-sparklines) A **sparkline** is a trend small enough to sit in a sentence: direction and shape at a glance — not a dashboard panel with axes. In React, that means a word-sized SVG mark next to a number or inside a table cell, where a full chart library would be too heavy and too loud. This page covers that mark in `@microcharts/react`. Props, variants, and edge cases live on [Sparkline](/docs/charts/sparkline). ```tsx <Sparkline data="[3, 5, 4, 8, 6, 9]" width="120" height="32" title="Weekly revenue" /> ``` ## Install [#install] Both steps are required — package and stylesheet: ```tsx import { Sparkline } from "@microcharts/react/sparkline"; import "@microcharts/react/styles.css"; // once, at the app root <Sparkline data={[3, 5, 4, 8, 6, 9]} title="Weekly revenue" />; ``` Measured size for this chart: <ChartSize slug="sparkline" /> gzip (CI-enforced). Catalog-wide band: <SizeMarketing />. The default export is static — RSC-safe, zero client JavaScript. Add `@microcharts/react/sparkline/interactive` only when hover, keyboard, touch, or selection is needed. ## Where it sits [#where-it-sits] Same component in four homes — product UI, report, docs, and an AI reply: Placement recipes: [Composition](/docs/composition). When this library fits vs a full chart library: [When to use microcharts](/docs/when-to-use). ## About `react-sparklines` [#about-react-sparklines] Many searches still land on [`react-sparklines`](https://www.npmjs.com/package/react-sparklines) (Boris Yankov) — about **250k downloads** in the week ending **2026-07-21**, last npm publish **2017-07-27** (`1.7.0`). Same visual idea; a different era of React (class-component patterns, `prop-types`, no generated accessible summary, not aimed at RSC). The measured side-by-side lives at [microcharts vs react-sparklines](/docs/vs-react-sparklines). microcharts is not that package rewritten. It is a word-sized catalog — <CatalogTotal /> types, one grammar — where Sparkline is one chart: `data` alone renders, accessible by default (`role="img"` + a summary from the data), static RSC entry, **zero runtime dependencies**. If `react-sparklines` still fits your stack, that is a valid choice. If you want the contract above, start here. ## When not to use a sparkline [#when-not-to-use-a-sparkline] * Exact category comparison → [MiniBar](/docs/charts/mini-bar) or [SparkBar](/docs/charts/sparkbar) * Value against a target → [Bullet](/docs/charts/bullet) * Part-to-whole → [SegmentedBar](/docs/charts/segmented-bar) or [MicroDonut](/docs/charts/micro-donut) * Full axes, legend, brush, zoom → a [full chart library](/docs/full-chart-libraries) ## Related marks [#related-marks] * [SparkBar](/docs/charts/sparkbar) — discrete magnitudes or win–loss * [DualSparkline](/docs/charts/dual-sparkline) — two series, one scale * [TrendArrow](/docs/charts/trend-arrow) — direction as a glyph * [Delta](/docs/charts/delta) — a single signed change * [Horizon](/docs/charts/horizon) — wide-range series in a slim band ## Next [#next] * [Sparkline API](/docs/charts/sparkline) * [Inline charts](/docs/inline-charts) * [When to use microcharts](/docs/when-to-use) * [Quickstart](/docs/quickstart) # Sizing & scaling (/docs/sizing) Every chart is a single `<svg>` with a `viewBox` and `preserveAspectRatio`, so scaling is a solved problem: give it a size in whatever way suits the layout and the geometry follows. There's no `ResizeObserver`, no layout effect, and no client JavaScript involved — a static chart scales purely through SVG and CSS. ## The three ways to size a chart [#the-three-ways-to-size-a-chart] | You want… | Do this | | ---------------------------- | -------------------------------------------------------- | | A sensible default | Pass nothing — every chart has an intrinsic box. | | An exact pixel size | Set `width` / `height` props (where the chart has them). | | To fill whatever contains it | Add `style={{ width: "100%", height: "auto" }}`. | > `width`/`height` are the common case, not a universal one. Grid charts derive their box from the cell instead — `ActivityGrid`, `CalendarStrip`, `GardenGrid` and `CohortTriangle` take `cell` and `gap`, `Honeycomb` takes `cell`, and `ConfusionGrid` takes `size`. The box then follows from the number of cells, so you tune the cell, not the frame. Glyph marks (`StatusDot`, `TrendArrow`, `MoonPhase`, `DicePips`, and friends) have one fixed intrinsic box and are sized with CSS. And `TokenConfidence` isn't an `<svg>` at all — it's text, so it inherits the font size of whatever it sits in. Everything below about `viewBox` scaling applies to the SVG charts. ## Default: data alone [#default-data-alone] `data` alone always renders something correct — at the chart's own intrinsic size. Each chart type ships a default box tuned to its shape: a Sparkline defaults to a wide, short 80 × 20, while a RubricStrip has no fixed default height at all — it grows a row per criterion. Good for dropping a mark into a table cell or a sentence without thinking about dimensions. ```tsx `" > <Sparkline data="[3, 5, 4, 8, 6, 9]" title="Weekly revenue" /> ``` ## Fixed size: width & height [#fixed-size-width--height] `width` and `height` are **viewBox units** — and because a static chart renders `<svg width={…} height={…}>`, they also set the rendered pixel box. So one pair of numbers controls both the coordinate space the geometry is drawn in and the size on screen. ```tsx `" > <Sparkline data="[3, 5, 4, 8, 6, 9]" width="200" height="48" title="Weekly revenue" /> ``` > Because `width`/`height` set the viewBox, they change how much room the geometry has — a taller RubricStrip gives each criterion a thicker row, a wider Sparkline spreads its points further apart. They are layout dimensions, not a zoom level. ## Fill the container [#fill-the-container] To make a chart fluid, stop pinning its pixel size and let CSS drive the width instead. The `viewBox` keeps the aspect ratio, so `height: auto` follows the width automatically. This is the one-liner for a KPI card, a responsive dashboard tile, or a full-width hero: ```tsx <Sparkline data={data} style={{ width: "100%", height: "auto" }} /> ``` The chart now grows and shrinks with its parent. Constrain it by sizing the container (or add a `max-width`), not the chart: ```tsx <div style={{ width: "100%", maxWidth: 320 }}> <Sparkline data={data} style={{ width: "100%", height: "auto" }} /> </div> ``` You can still pass `width`/`height` alongside fluid CSS — they become the chart's intrinsic aspect ratio and its size before CSS overrides the width. If you use a utility framework, the equivalent classes work just as well (`className="w-full h-auto"`). To give a whole row of charts one identical box rather than sizing each by hand, put `width`/`height` on `SparkGroup` instead: it enforces them on every series child that didn't set its own (and shares one scale while it's there — see [Formatting & scale](/docs/formatting#scale-the-domain-decision)). > `.mc-root` is `display: inline-block` by default (so a chart flows next to text). When you make one fill a block-level container, it behaves as expected — but if you ever see it not stretching, that's the reason: give it a `display: block` or a flex/grid parent. ## Interactive charts size the same way [#interactive-charts-size-the-same-way] Everything above applies **unchanged** to the `…/interactive` entries. An interactive chart wraps its SVG in a focusable `<span>` (it owns the pointer, keyboard, and touch gestures for the whole chart), but that wrapper and the SVG are always the **same box**: the wrapper is an `inline-block` that hugs its child, and the composed SVG inside is pinned to `width: 100%; height: auto`. Your `style` merges over the wrapper's base style and your `className` composes after its base class, so the same recipe fills it: ```tsx import { Sparkline } from "@microcharts/react/sparkline/interactive"; // identical to the static entry — fills its container <Sparkline data={data} style={{ width: "100%", height: "auto" }} />; ``` > Because the wrapper and the SVG share one box, hit-testing is exact at any size: the crosshair, highlight, and readout land under the cursor, a touch drag scrubs the unit actually beneath the finger, and a pinned selection stays on the right unit when the box reflows. An interactive chart is its static twin plus interaction, never a different size. ## Inline in a sentence [#inline-in-a-sentence] A word-sized chart in running prose should scale with the **font**, not a pixel box. Wrap it in `className="mc-inline"` (shipped in `styles.css`) and size it in `em` so it rides the text: ```tsx <p> Revenue is up this week{" "} <span className="mc-inline"> <Sparkline data={[3, 5, 4, 8, 6, 9]} style={{ height: "1em", width: "auto" }} /> </span>{" "} and holding. </p> ``` `mc-inline` handles vertical alignment; the `em` height ties the mark to the surrounding type size, so it stays proportional wherever the text lands. Alignment is a **baseline seat**, not a fixed nudge: the wrapper is an `inline-flex` box whose only child is the SVG, so it takes its baseline from the SVG's bottom edge and the mark stands on the text baseline exactly like a glyph. That's typeface-independent — bars sit where letters sit in any font. Symmetric glyph marks have no bottom edge to stand on, so `mc-inline` centers those on the cap band instead: `TrendArrow`, `StatusDot`, `MoonPhase`, `DicePips`, the radial dials and the other glyph shapes read like an icon set in running prose. You don't opt in. Which seat a mark gets isn't guessed from its class name — each chart reports its own plot box, measured in the same viewBox units it draws in, and the stylesheet seats the mark from that. So a chart whose padding changes can't drift out of alignment, and a chart that changes shape with its props carries the right seat for each: `SparkBar` stands on the baseline in bar mode and centers in win-loss, because only one of those has a real floor. Two tokens let you nudge the result if a particular typeface needs it — `--mc-inline-nudge` for every mark, and `--mc-glyph-nudge` for centered ones only. > Leave `<Delta>` bare — no `mc-inline` wrapper. It renders as inline text and already owns its own baseline. ## Strokes stay crisp at any scale [#strokes-stay-crisp-at-any-scale] Scaling an SVG normally thickens or thins its lines. microcharts sets `vector-effect: non-scaling-stroke` on data marks, so a line drawn at 200 px and the same line at 800 px keep the **same visual stroke weight** — the geometry scales, the ink doesn't. Rectilinear marks also use `shape-rendering: crispEdges` so bars and grids stay sharp. You get responsive sizing without the usual blurriness or weight drift. Stroke weight is a token, not a size artifact — set `--mc-stroke-width` (see [Theming](/docs/theming)) if you want it heavier or lighter, independent of how big the chart is. For a whole dense context — a table packed with sparklines — reach for `--mc-density`: one scalar that scales stroke weight, label size, and small-multiple gap together (`< 1` tighter, `> 1` airier). It tunes the ink and type, never the box, so `width`/`height` still own the geometry. # Theming (/docs/theming) microcharts theming is CSS custom properties, all the way down. There's no theme provider you *have* to wire up and no Tailwind requirement — set a `--mc-*` variable at any scope and every chart inside it retunes, with zero re-render and no build step. (Prefer a React component to a raw attribute? [`MicroProvider`](#a-component-api-if-you-prefer) wraps the same contract.) Two ideas carry the whole system: **a token** is one variable you set, and **a scope** is where you set it. Learn those two and the rest of this page is just the vocabulary — every colour, weight, and timing you can reach for, and a studio that hands you any combination as ready-to-paste CSS. ## Override a token [#override-a-token] ```css .brand { --mc-accent: #7c3aed; --mc-stroke-width: 2; } ``` Every chart inside `.brand` now draws with that accent and stroke weight. Precedence is predictable: a **prop** wins over a **CSS-variable scope**, which wins over a **preset**, which wins over the built-in default. ```tsx <Sparkline data={data} color="#7c3aed" /> <Sparkline data={data} color="var(--mc-positive)" />`" > <Sparkline data="[3, 5, 4, 8, 6, 9]" width="110" height="30" title="Default" /> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="110" height="30" color="#7c3aed" title="Custom" /> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="110" height="30" color="var(--mc-positive)" title="Token" /> ``` ## Scope it anywhere [#scope-it-anywhere] Because the tokens cascade, the scope is yours to choose — the whole app, one brand section, a single card, or one chart. Set a token high and every chart below inherits it; override it lower and only that subtree changes. ```tsx // app-wide, once <html style={{ "--mc-accent": "var(--brand-500)" }}> // just this card's charts <div style={{ "--mc-stroke-width": 2, "--mc-gap": "0.15em" }}> <SparkBar data={weekly} /> </div> ``` Bind `--mc-accent` to your existing brand variable and the charts follow your design system automatically — no per-chart props, no duplicated color values. ## The token set [#the-token-set] That's the whole mechanism. What's left is the vocabulary: about two dozen custom properties cover the entire surface, and setting any of them at any scope retunes every chart inside. Here are the colour tokens with their built-in light and dark values — every chip is the real shipped default, click to copy the hex: <TokenSwatches /> Below is the same set as raw CSS — the colours plus the geometry, motion, and readout-surface tokens — ready to paste and override. (Want a specific style or accent instead of the bare defaults? The [studio](#copy-tokens) a little further down builds any combination for you.) ```css :root { /* Semantic colour */ /* Default ink: lines, bars, labels. Dark mode is hand-tuned, not inverted. */ --mc-stroke: #1a1917; /* Good direction — colour-blind-safe viridian; pair with ▲. */ --mc-positive: #0e7a5f; /* Bad direction — colour-blind-safe terracotta; pair with ▼. */ --mc-negative: #bd4b2d; /* No-signal marks: baselines, inactive points, empty cells. */ --mc-neutral: #8a8986; /* Emphasis colour — rebind to your brand. */ --mc-accent: #1f6091; /* Normal-range shading, derived from the ink. */ --mc-band: color-mix(in oklab, var(--mc-stroke) 8%, transparent); /* MoonPhase lit area — warm amber; mono/print/eink retune it with the ink. */ --mc-moon: #c1922f; /* Categorical palette — matte jewel tones; multi-series only, lightness-ordered. Each has a hand-tuned brighter twin on dark surfaces (same hue, lifted). */ --mc-cat-1: #d2982f; --mc-cat-2: #5b9fd4; --mc-cat-3: #2e8c66; --mc-cat-4: #285788; --mc-cat-5: #c2543a; --mc-cat-6: #a85c8c; /* Geometry */ /* Light by default for inline use; bump to ~2 when standalone. */ --mc-stroke-width: 1.5; /* Spacing between grouped marks; em-based so it scales with the font. */ --mc-gap: 0.25em; /* Uniform density scale — compact (<1) vs comfortable (>1). Tunes stroke weight, label size, and small-multiple gap together; the box set by width/height is untouched. */ --mc-density: 1; /* Direct-label text size, relative to the chart's font. */ --mc-label-size: 0.75em; /* Direct-label weight. */ --mc-label-weight: 400; /* `.mc-inline` seats marks on the text baseline (font-independent). This is an optional extra optical shift on top — 0 by default; set it only if a particular face wants marks a hair off the line. */ --mc-inline-nudge: 0em; /* Extra optical shift for centred marks (arrow, dot, moon, dials, strips) on top of the cap-band seat — font-relative, negative lifts. 0em by default: the seat already lands on the true cap midpoint, so there is nothing left to correct unless a display face has an unusual cap ratio. */ --mc-glyph-nudge: 0em; /* Motion & type */ /* Motion duration — readout transitions, value pulses, entrance animation. */ --mc-duration: 300ms; /* Ease-out entrance; no bounce or loop. */ --mc-easing: cubic-bezier(0.22, 1, 0.36, 1); /* Inherits the host UI font + tabular numerals by default. */ --mc-font: inherit; /* Face for figures + labels — tracks --mc-font; point at a brand or mono face to give numbers their own typeface without touching the page font. */ --mc-font-numeric: var(--mc-font); /* Interactive readout chip (hover, focus, or a pinned selection). Defaults to system canvas. */ --mc-surface: Canvas; --mc-surface-ink: CanvasText; --mc-surface-edge: color-mix(in oklab, CanvasText 16%, transparent); } ``` ## Semantic vs categorical color [#semantic-vs-categorical-color] The colour tokens split into two groups, and knowing which is which is what keeps a theme honest. **Semantic tokens keep their meaning.** Swapping `--mc-accent` retints the one emphasis color, but `--mc-positive`/`--mc-negative` still mean up and down — so a preset can restyle a chart without ever changing what it says. Color encodes; it never merely decorates. **Categorical colors are a last resort.** Most microcharts show one series and never touch the palette. When a chart genuinely needs several, the six `--mc-cat-*` hues are lightness-ordered for grayscale and colour-vision separation, and gold leads because true yellow is too low-contrast on a light surface. To recolour the series on *one* instance without touching the global palette, the categorical charts (`SegmentedBar`, `StackedArea`, `PartitionStrip`, `Hypnogram`, `MicroDonut`) take a `colors` array — cycled per series, overriding `--mc-cat-*` just there. A rolled-up "Other" segment stays neutral rather than taking a series colour. ```tsx `"> <SegmentedBar data="[ { label: "A", value: 34 }, { label: "B", value: 26 }, { label: "C", value: 22 }, { label: "D", value: 18 }, ]" colors="["#2563eb", "#db2777", "#65a30d", "#f59e0b"]" width="220" height="16" title="Custom series colours" /> ``` ## Presets [#presets] Setting tokens by hand is one path; a **preset** is a whole look bundled under one name, applied with a `data-mc-theme` attribute — pure CSS, zero JavaScript. They change how charts *look*, never what the data *means*. `modern` is what you get with no attribute at all: it's the base token set, not a bundle layered on top, so there's nothing to apply. ```tsx <Sparkline data={data} dots="minmax" /></div> {/* modern — the default, no attribute */} <div data-mc-theme="editorial"><Sparkline data={data} dots="minmax" /></div> <div data-mc-theme="vivid"><Sparkline data={data} dots="minmax" /></div> <div data-mc-theme="mono"><Sparkline data={data} dots="minmax" /></div>`" > <div> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="100" height="28" dots="minmax" title="modern" /> </div> <div data-mc-theme="editorial"> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="100" height="28" dots="minmax" title="editorial" /> </div> <div data-mc-theme="vivid"> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="100" height="28" dots="minmax" title="vivid" /> </div> <div data-mc-theme="mono"> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="100" height="28" dots="minmax" title="mono" /> </div> ``` What each preset retunes — every other token stays at its default: <PresetDeltas /> The last two — `print` and `eink` — are output-context bundles rather than a look you'd ship on screen. `print` pins a near-black ink, deepens the valence colours for CMYK, and thins the stroke to `1.25`; `eink` drops to grayscale and lets sign ride lightness (positive black, negative gray) with a `2` stroke for a low-refresh e-paper panel. Apply them the same way — `data-mc-theme="print"` on the region you're about to render. Both pin a fixed light-surface ink, so both also ship hand-tuned dark twins: on a dark viewer `eink` flips to true night mode (white ink on black) and `print` lifts to a dark-paper ink, while the stroke weight and band identity carry over. The look presets — `editorial`, `mono`, `vivid`, `print`, `eink` — also answer to `data-mc-preset`, the page-global form: set it once on `<html>` for an app shell, and a nearer `data-mc-theme` still wins by proximity. `dark` is the exception, matching `data-mc-theme="dark"` only, because it's a colour-scheme scope rather than a look you'd pin app-wide. > Every preset above carries a **Copy tokens** button, and the [studio below](#copy-tokens) lets you pair any preset with your own accent and copy the result for both modes. This site's appearance menu (the palette icon in the nav) applies the same bundles live across every page — and picking an accent there re-hues every chart on the site, including the categorical palette, because it derives one with [`defineTheme`](#build-a-theme-from-one-colour) exactly like the studio does. It's the exact token contract you'd use in your own app. ## Copy the tokens [#copy-tokens] Everything above, in one place — the live studio. Pick a style, add your brand accent, choose a mode, and copy the exact `--mc-*` block, light and hand-tuned dark together, ready to paste into your app. The preview renders real charts in both modes and names each role it paints, so a choice shows up the instant you make it: the emphasis line takes your accent *and* the categorical bars re-hue to a matched palette **derived from it** by [`defineTheme`](#build-a-theme-from-one-colour) — the same engine the nav's appearance menu uses to re-theme the whole site. What you preview is exactly what you copy, and exactly what the library ships — never an approximation. <TokenStudio /> Paste the CSS into any stylesheet and every chart in scope retunes. Prefer the component API? Switch the format to a tokens object and spread it onto [`MicroProvider`](#a-component-api-if-you-prefer) — or reach for [`defineTheme`](#build-a-theme-from-one-colour) directly to derive that matched palette in code. ## A component API, if you prefer [#a-component-api-if-you-prefer] Everything above works through plain attributes and CSS variables — but if you'd rather set the theme in JSX, `MicroProvider` wraps the same contract in a component. It's hook-free and RSC-safe, so it works in Server Components too. ```tsx import { MicroProvider } from "@microcharts/react"; <MicroProvider theme="editorial" tokens={{ "--mc-accent": "var(--brand-500)" }}> <Sparkline data={data} /> </MicroProvider>; ``` It renders a single `<div>` that sets `data-mc-theme` (the preset) plus any `tokens` as inline `--mc-*` custom properties — identical to writing them by hand. `theme="modern"` writes no attribute, since modern *is* the base token set. `theme` takes any preset (`modern`, `editorial`, `mono`, `vivid`, `dark`, plus the output-context `print` and `eink`); `tokens` takes any `--mc-*` overrides. Reach for whichever reads better in your code — it's the same cascade underneath. ## Build a theme from one colour [#build-a-theme-from-one-colour] Setting a token or two by hand is the common case. For a whole brand theme — a matched categorical palette *and* hand-tuned dark twins for every colour — reach for `defineTheme` from `@microcharts/react/theme`. Hand it your brand accent and it derives the rest in OKLCH: a harmonized, colour-blind-safe categorical palette and a lifted dark-mode twin for each token. It never nudges the positive/negative hues off their CVD-safe green/vermillion split, so a derived theme stays as honest as the defaults. ```tsx import { defineTheme } from "@microcharts/react/theme"; import { MicroProvider } from "@microcharts/react"; const brand = defineTheme({ accent: "#6d28d9" }); // spread the tokens onto one scope… <MicroProvider style={brand.style}> <SegmentedBar data={mix} /> </MicroProvider>; // …or emit a global stylesheet — includes a prefers-color-scheme: dark block const css = brand.css(":root"); ``` One accent, a full derived palette (these are the real values `defineTheme` returns): ```tsx <SegmentedBar data={mix} title="Derived palette" /> </MicroProvider>`" > <div style="{ "--mc-accent": "#6d28d9", "--mc-cat-1": "#8b7cc5", "--mc-cat-2": "#9a4f72", "--mc-cat-3": "#bc7548", "--mc-cat-4": "#6d7218", "--mc-cat-5": "#2d9e82", "--mc-cat-6": "#04759f", }" > <SegmentedBar data="[ { label: "A", value: 34 }, { label: "B", value: 26 }, { label: "C", value: 18 }, { label: "D", value: 12 }, { label: "E", value: 10 }, ]" width="220" height="16" title="Derived palette" /> </div> ``` The result carries everything you need for any delivery: `vars` (a `--mc-*` object), `darkVars` (the derived dark twins, empty when `dark: false`), `style` (an alias of `vars`, ready to spread onto `MicroProvider` or any element), `css(selector = ":root")` (a string with the `prefers-color-scheme: dark` block included), `toString()` (the same as `css(":root")`), and `extend()` to spin a variant off an existing theme. Extend a preset, pin any token, or pass an explicit palette when you don't want derivation: ```tsx // extend a preset — the brand accent flows through defineTheme({ extends: "editorial", accent: "var(--brand-500)", }); // bring your own categorical palette (no derivation) defineTheme({ accent: "#6d28d9", cat: ["#2563eb", "#db2777", "#65a30d"], }); // derive a specific number of categorical tones instead of the default six defineTheme({ accent: "#6d28d9", cat: 3 }); // opt out of accent-seeded derivation, or out of dark twins entirely defineTheme({ accent: "#6d28d9", derive: false }); defineTheme({ accent: "#6d28d9", dark: false }); // override just some dark twins (the rest stay auto-derived) defineTheme({ accent: "#6d28d9", dark: { accent: "#a78bfa" } }); // compose a compact variant off an existing theme defineTheme({ density: 0.85 }).extend({ labelWeight: 500 }); // pin geometry directly — strokeWidth, gap, labelSize, labelWeight, density defineTheme({ accent: "#6d28d9", strokeWidth: 2 }); ``` It's pure, dependency-free, and tree-shaken out of any bundle that never imports it. ## Density [#density] `--mc-density` is a single scalar that scales stroke weight, label size, and small-multiple gap together — one knob for compact tables (`< 1`) or an airier standalone layout (`> 1`). It tunes the ink and type, not the box: the plot size still comes from `width`/`height`, so nothing reflows unexpectedly. ```css /* a denser table of sparklines */ .metrics-table { --mc-density: 0.85; } ``` One asymmetry worth knowing: **stroke and gap scale without limit, but the label stops scaling at 1.25.** Direct labels sit in a gutter the chart reserves from a character-count estimate while it draws — server-side, where text cannot be measured. That reservation is fixed at render time and cannot see a CSS variable set later, so past about 1.25 the text outgrows the space held for it and paints outside the chart. Below `1` there is no such limit: the label shrinks inside a gutter already reserved for something bigger, which is always safe. So `--mc-density: 2` gives you double-weight strokes and double gaps, with labels at 1.25×. If you want genuinely larger text, scale the chart — `width`/`height`, or `--mc-label-size` — rather than leaning on density. ## The font [#the-font] `--mc-font` defaults to `inherit`, so charts adopt the font of whatever contains them and read as part of your interface. That means the rule is really about your page, not the library: if the surrounding page sets a `font-family`, charts follow it for free. If it doesn't — as in some minimal starters and code sandboxes — SVG text falls back to the browser default (usually a serif), and labels come out looking wrong. Two fixes, either works: give your page a font the normal way, or font the charts directly by pointing `--mc-font` at a stack. ```css :root { /* charts only — the rest of the page is untouched */ --mc-font: system-ui, sans-serif; } ``` Numbers always render with `tabular-nums` regardless, so columns of figures stay aligned in any font. Want the figures in a dedicated face — a tabular numeric font, or a mono for a data-dense KPI — without changing the label font? Point `--mc-font-numeric` at it; it defaults to `--mc-font`, so leaving it alone keeps everything on one typeface. `--mc-label-weight` (default `400`) does the same for label weight. ```css :root { --mc-font: Inter, sans-serif; /* labels */ --mc-font-numeric: "IBM Plex Mono", monospace; /* figures */ } ``` ## The readout surface [#the-readout-surface] The only opaque plane in the whole library is the value chip an interactive chart shows for its active unit — under the pointer, under keyboard focus, or pinned in place after a click, tap, or **Enter**. Its three `--mc-surface*` tokens default to the system `Canvas`, so it adapts to light, dark, and forced-colors with no configuration. Point them at your popover tokens when you want the chip to match a themed surface exactly — one set of tokens covers the hovered, focused, and pinned states alike. ## Dark mode and forced colors [#dark-mode-and-forced-colors] Dark values are hand-tuned per token — never auto-inverted, so overriding one light value can't quietly break the dark surface. microcharts follows `prefers-color-scheme` out of the box, and you can force a scope with `data-mc-theme="dark"`. Charts never paint their own background, so they always sit cleanly on your surface. If your app toggles theme with a **class** (next-themes `.dark`, a `[data-theme]` attribute, …) rather than the OS media query, rebind the tokens under that class the same way you bind accent — the library's media-query defaults are `:where()` zero-specificity, so your class rules win: ```css :root { --mc-accent: var(--brand); } .dark { --mc-stroke: #eae9e6; --mc-positive: #45a385; --mc-negative: #df7856; --mc-accent: var(--brand); /* …or data-mc-theme="dark" on a scope, if you prefer the shipped dark bundle */ } ``` ### Frosted or translucent surfaces [#frosted-or-translucent-surfaces] Default valence inks clear 4.5:1 on opaque white and near-black. On a frosted glass / tinted panel the composited backdrop is quieter, so deepen `--mc-stroke` / `--mc-positive` / `--mc-negative` / `--mc-neutral` on that surface until contrast holds — don't patch chart CSS. (This docs site does exactly that under `:root` / `.dark` so marks stay legible on glass.) Under Windows High Contrast (`forced-colors`), the semantic tokens defer to system colors — ink to `CanvasText`, accent to `Highlight`, muted marks to `GrayText` — so a chart stays legible even when your palette is overridden entirely. `prefers-contrast: more` is handled too: charts bump `--mc-stroke-width` to `2` and deepen `--mc-band` from an 8% to a 16% mix of the ink, so lines and normal-range shading both gain weight without you configuring anything. # Troubleshooting (/docs/troubleshooting) Most issues trace back to one of a handful of causes. This page is the fast path to each fix; the full explanation for each one lives on its own guide page, linked below. ## Charts render with no color, no strokes, just plain shapes [#charts-render-with-no-color-no-strokes-just-plain-shapes] The stylesheet isn't loaded. Every visual property — color, stroke weight, label size, the whole theme — comes from `styles.css`, imported once: ```tsx import "@microcharts/react/styles.css"; ``` Without it, a chart is still valid, accessible SVG (the markup and the accessible name are both there), it just has no styling applied — geometry with no ink. See [Quickstart](/docs/quickstart#compatibility) for where to put the import in your framework. ## A chart is invisible (or nearly) on a colored or dark panel [#a-chart-is-invisible-or-nearly-on-a-colored-or-dark-panel] Charts never paint their own background — they're transparent SVG, always. On a plain light or dark page this is invisible because the built-in light/dark tokens track `prefers-color-scheme`. It breaks when a chart sits on a surface whose color doesn't match the *page's* color scheme — a dark-branded card on an otherwise light page, or a colored KPI tile — because the tokens don't know that scope looks dark; they only know what the OS/browser reports. Fix it by rebinding the token scope to match the surface, not the page: ```css .dark-panel { --mc-stroke: #f5f5f5; /* text + data strokes; add --mc-neutral for muted labels */ } ``` or force the whole preset for that scope: ```tsx <div data-mc-theme="dark"> <Sparkline data={data} /> </div> ``` See [Theming](/docs/theming) for the full token set and how scope, preset, and prop precedence works. ## `Error: ... 'use client' ...` when importing a chart [#error--use-client--when-importing-a-chart] You imported a chart's `/interactive` entry into a Server Component: ```tsx // ❌ interactive entries are client components — this throws in an RSC import { Sparkline } from "@microcharts/react/sparkline/interactive"; ``` Two ways out: render the static default entry instead if you don't actually need hover, keyboard, touch, or selection — ```tsx import { Sparkline } from "@microcharts/react/sparkline"; ``` — or, if you do need interactivity, move the import into a component marked `"use client"` and render that component from your server tree. See [Quickstart](/docs/quickstart#add-interactivity) for the static-vs-interactive split. ## `onPointFocus` / `onRunFocus` no longer fire [#onpointfocus--onrunfocus-no-longer-fire] They were removed when every interactive chart moved onto one shared contract. The replacement is `onActive`, which fires for the same reason on every chart in the catalog rather than under a different name per chart: ```tsx // ❌ removed <Sparkline data={data} onPointFocus={(i) => setHovered(i)} /> // ✅ one name, everywhere <Sparkline data={data} onActive={(d) => setHovered(d?.index ?? null)} /> ``` The payload is a `MicroDatum` — `{ index, value, label?, formatted? }` (`value` is the raw number, `formatted` the chart's ready-to-display string) — or `null` when the chart clears. `onPointFocus` on Sparkline and SparkBar and StreakSpark's `onRunFocus` map across directly. Note that `index` identifies the chart's *navigable unit*, which isn't always a series index: on Waveform it's a bucket, on Hypnogram a run, on SegmentedBar a segment. Each chart's page names its own unit. If you also want click-to-pin, add `onSelect` — see [Accessibility](/docs/accessibility#one-interaction-contract). ## `animate` does nothing [#animate-does-nothing] The entrance engine isn't loaded. `animate` is a flag; the code that runs the animation ships in a separate side-effect import you add once, anywhere in your client bundle: ```tsx import "@microcharts/react/motion"; ``` In development the chart logs exactly this to the console when the engine is missing. Three other reasons `animate` is correctly inert, none of them bugs: the reader has `prefers-reduced-motion: reduce`, the chart is a static entry (`animate` is an `/interactive`-only prop), or the markup came from the server and is being hydrated rather than freshly mounted — an entrance would mean animating content the reader can already see. The entrance also runs once per mount by design; remount with a changed `key` to replay it. ## The chart won't stretch to fill its container [#the-chart-wont-stretch-to-fill-its-container] `.mc-root` — the chart's own `<svg>` — is `display: inline-block` by default, so it flows next to text instead of stretching. Give it fluid sizing explicitly: ```tsx <Sparkline data={data} style={{ width: "100%", height: "auto" }} /> ``` and make sure the *parent* is block-level (a flex or grid item, or a `div`) — a chart can't grow past an inline parent no matter what you set on the chart itself. This is identical for `…/interactive` entries: `style`, `className`, and `width`/`height` size an interactive chart exactly the way they size its static twin, and hit-testing stays exact at any size — the crosshair tracks the cursor and a touch drag scrubs the unit under the finger. Full recipes, including the inline-in-a-sentence case, are on [Sizing & scaling](/docs/sizing). ## A chart stacks on its own line instead of sitting inline with text [#a-chart-stacks-on-its-own-line-instead-of-sitting-inline-with-text] This is usually a CSS reset, not a microcharts bug. `.mc-root`'s `display: inline-block` is declared inside a zero-specificity `:where()` so your styles always win — including ones you didn't mean to apply. Tailwind's Preflight sets a plain `svg { display: block; ... }` rule, which has *higher* specificity than any `:where()` selector and so overrides it, dropping the chart onto its own block-level line. Re-assert the layout you want at the call site: ```tsx <Sparkline data={data} className="inline-block" /> ``` or wrap it in `className="mc-inline"` for text-flow placement — see [Sizing & scaling](/docs/sizing#inline-in-a-sentence). ## Chart labels look wrong — a serif fallback, or mismatched with the page [#chart-labels-look-wrong--a-serif-fallback-or-mismatched-with-the-page] Charts inherit `font-family` from the page; they don't set one of their own. If the surrounding page never declares a font (a bare sandbox, a minimal starter), SVG text falls back to the browser's default serif. See [Theming → The font](/docs/theming#the-font) for why it inherits and how to set it per-scope. # microcharts vs Chart.js for inline charts (/docs/vs-chartjs) [Chart.js](https://www.chartjs.org) is a Canvas-first chart library with a large plugin ecosystem, usually wrapped by [`react-chartjs-2`](https://react-chartjs-2.js.org) in React apps. microcharts is not a replacement for it — a dense analyst dashboard or a report full of chart panels is Chart.js territory. This page compares the two for one narrow job: a chart the size of a word, inside a sentence, a table cell, or a KPI card. The broader positioning lives in [When to use microcharts](/docs/when-to-use) and [Full chart libraries](/docs/full-chart-libraries). ## The numbers [#the-numbers] <VsChartJsTable /> microcharts numbers come from `.size-limit.json` — the CI gate, re-measured on every build. The Chart.js figures are pinned with version and date; they are orientation, not a scoreboard. ## Where the difference actually shows [#where-the-difference-actually-shows] **Renderer.** Chart.js draws to a `<canvas>`, and a canvas only exists in the browser — there is no static-HTML output path. The chart appears after JavaScript runs. microcharts renders SVG markup, so the mark is real DOM: it exists in the server-rendered HTML, prints correctly, and scales crisply at any zoom. **Server Components.** `react-chartjs-2` manages the canvas with hooks and effects, so it runs in a client boundary and ships Chart.js to the browser. The microcharts default export is hook-free static SVG — an RSC can render it with zero client JavaScript. **Accessibility.** A canvas is a bitmap to assistive technology; the Chart.js docs recommend supplying your own fallback content or ARIA labeling per chart, and plugins exist to help. That path works — it is just manual. Every microchart defaults to `role="img"` plus a natural-language summary generated from the data. **Text and theming.** Inline marks sit next to your text, so they must inherit its rhythm. SVG takes CSS custom properties, `currentColor`, and container-relative sizing directly; a canvas repaints through JavaScript when the theme flips. ## Reach for Chart.js [#reach-for-chartjs] * Dashboard or report canvases with many series and heavy point counts * You already run Chart.js configs or depend on its plugin ecosystem * Canvas rendering is a requirement, not an implementation detail ## Reach for microcharts [#reach-for-microcharts] * The mark lives inline — prose, cells, tabs, KPI cards, streamed AI replies * You want the chart present in server-rendered HTML, with zero client JS by default * You want an accessible name without per-chart wiring * Per-mark budget: <SizeMarketing /> gzip, zero runtime dependencies ## What this page is not saying [#what-this-page-is-not-saying] * Not "Canvas is wrong" — above a few thousand points it is usually right * Not "Chart.js cannot be made accessible" — it can; it is manual * The gzip figures are dated pins, not live measurements ## Next [#next] * [Full chart libraries](/docs/full-chart-libraries) — Recharts and Chart.js in one view * [microcharts vs Recharts](/docs/vs-recharts) * [When to use microcharts](/docs/when-to-use) * [Accessibility](/docs/accessibility) — what the defaults actually do # microcharts vs MUI X Sparkline — bundle size and RSC comparison (/docs/vs-mui-x-sparkline) [MUI X Charts](https://mui.com/x/react-charts/) ships `SparkLineChart` — an inline-sized chart from the same family as its full Line, Bar, and Pie charts, themed by and integrated with Material UI. If your product is built on MUI and the sparkline sits in a MUI dashboard, that integration is a real advantage and this page may talk you out of nothing. The comparison matters when the mark must be cheap, static, or independent of MUI: a table column of trends, a KPI row in an RSC, a chart in a streamed AI reply. ## The numbers [#the-numbers] <VsMuiXTable /> The two MUI scenarios are deliberate: inside a MUI app the Material core is already in your bundle, so the sparkline's marginal cost is the smaller figure. Without MUI, `@mui/material` and `@mui/system` are required peer dependencies — you install and ship them to render one sparkline. ## Where the difference actually shows [#where-the-difference-actually-shows] **Bundle cost.** `SparkLineChart` shares MUI X's charting core (data providers, interaction plugins, vendored d3). That architecture is what makes the full chart family consistent — and it is why one sparkline carries tens of kilobytes. microcharts charges per chart subpath: <ChartSize slug="sparkline" /> for Sparkline, catalog band <SizeMarketing /> gzip. **Server Components.** `SparkLineChart` is marked `'use client'` — the server can emit initial HTML, but the component always hydrates and ships its JavaScript. The microcharts default export is hook-free static SVG with zero client JS; interactivity is a separate `/interactive` import. **Accessibility defaults.** As published, the `SparkLineChart` SVG renders with `aria-hidden="true"` and no accessible name — the chart is invisible to assistive technology unless you label it yourself. Every microchart defaults to `role="img"` with a natural-language summary generated from the data. **Theming.** MUI X charts theme through the MUI theme object — coherent if you live there. microcharts themes through `--mc-*` CSS custom properties at near-zero specificity, so it follows any design system, including a MUI one. ## Reach for MUI X Sparkline [#reach-for-mui-x-sparkline] * Your app is already on MUI and the chart sits among MUI components * You want one vendor for the sparkline and the full charts beside it * You use MUI X's tooltip, highlighting, and animation stack elsewhere ## Reach for microcharts [#reach-for-microcharts] * The mark must not pull MUI (or anything) into the bundle — zero runtime dependencies * You render from RSCs and want zero client JavaScript for static marks * Accessibility should be the default, not a labeling task per chart * You need chart types beyond sparklines at word size — <CatalogTotal /> types, one grammar ## What this page is not saying [#what-this-page-is-not-saying] * Not "MUI X is bloated" — the shared core is the price of a consistent full-chart family * Not "never use SparkLineChart" — inside a MUI dashboard it is the coherent choice * MUI X Charts (community) is MIT and actively maintained; the sizes are dated pins from the published package ## Next [#next] * [When to use microcharts](/docs/when-to-use) * [microcharts vs Recharts](/docs/vs-recharts) * [React sparklines](/docs/react-sparklines) * [Theming](/docs/theming) — fitting charts into an existing design system # microcharts vs react-sparklines — React sparkline comparison (/docs/vs-react-sparklines) [`react-sparklines`](https://www.npmjs.com/package/react-sparklines) put sparklines into thousands of React apps and still gets massive weekly downloads. It is the package many "react sparkline" searches land on, so if you are choosing between it and microcharts, this page is the factual side-by-side. It is not a takedown — the package earned its adoption. ## The numbers [#the-numbers] <VsReactSparklinesTable /> ## Where the difference actually shows [#where-the-difference-actually-shows] **Maintenance.** `react-sparklines` last published in 2017 (`1.7.0`). It predates hooks and Server Components — nothing from that era can be expected to target them. microcharts is actively maintained against React 18 and 19, with StrictMode-safe rendering tested in CI. **Accessibility.** `react-sparklines` renders a bare `<svg>` — no `role`, no `<title>`, no accessible name; a screen reader finds nothing. Every microchart is `role="img"` with a natural-language summary generated from the data (`describeSeries`), and interactive entries add keyboard navigation with a polite live region. **Server Components.** `react-sparklines` components are class components, which need a client boundary in an App Router app. The microcharts default export is hook-free static SVG that renders directly in an RSC with zero client JavaScript. **Scope.** microcharts is a word-sized catalog — <CatalogTotal /> chart types, one grammar: `data` alone renders something correct, and the same prop names mean the same thing on every chart. Sparkline is one entry in it. `react-sparklines` is one visual idea with composable overlays. **Size.** Both are small. `react-sparklines` is a single \~7.9 kB gzip package; microcharts charges per chart subpath (<ChartSize slug="sparkline" /> for Sparkline) with a CI gate that keeps every chart inside its budget. ## When react-sparklines is still fine [#when-react-sparklines-is-still-fine] * A legacy codebase already uses it, the charts are decorative, and nothing is broken * You need its exact composable-overlay API and have your own accessibility layer No urgency to migrate in those cases. The gaps above matter when accessibility, RSC, or maintenance actually bite. ## Migrating [#migrating] The shapes map directly: ```tsx // react-sparklines import { Sparklines, SparklinesLine } from "react-sparklines"; <Sparklines data={[3, 5, 4, 8, 6, 9]} width={100} height={20}> <SparklinesLine color="steelblue" /> </Sparklines>; // microcharts import { Sparkline } from "@microcharts/react/sparkline"; <Sparkline data={[3, 5, 4, 8, 6, 9]} width={100} height={20} color="steelblue" title="Weekly revenue" />; ``` `title` gives the chart its accessible subject; the summary is generated from the data. Bars map to [SparkBar](/docs/charts/sparkbar), reference lines to [`<Threshold>`](/docs/annotations). ## Next [#next] * [React sparklines](/docs/react-sparklines) — the mark itself, in depth * [Sparkline API](/docs/charts/sparkline) * [When to use microcharts](/docs/when-to-use) * [Accessibility](/docs/accessibility) # microcharts vs Recharts — inline charts comparison (/docs/vs-recharts) [Recharts](https://recharts.org) is a full chart library and microcharts is not a replacement for it. If your page *is* the chart — axes, legend, tooltip, brush — stop reading and use Recharts. This page compares the two for exactly one job: a word-sized chart *inside* an interface, where the surface is mostly words and UI. The broader positioning lives in [When to use microcharts](/docs/when-to-use) and [Full chart libraries](/docs/full-chart-libraries). This page is the measured detail for the Recharts decision. ## The numbers [#the-numbers] <VsRechartsTable /> Both microcharts columns come from `.size-limit.json`, the CI gate that fails the build when a chart grows past its budget. The Recharts numbers are pinned with version, method, and date — they are orientation, not a scoreboard, and they will age. ## Where the difference actually shows [#where-the-difference-actually-shows] **Bundle cost per mark.** A tree-shaken Recharts `LineChart` carries the shared Recharts core. That cost is fine amortized over a dashboard; it is hard to justify for one sparkline in a table header. microcharts imports one chart per subpath, so a page that uses only `Sparkline` pays only for `Sparkline`. **Server Components.** Recharts components are hook-based, so in an App Router app they run inside a client boundary and ship their JavaScript. The microcharts default export is hook-free static SVG — it renders in an RSC with zero client JavaScript, and interactivity is a separate opt-in `/interactive` import. **Accessibility defaults.** Recharts ships an accessibility layer, on by default in v3 — keyboard navigation and ARIA roles on the chart surface. A natural-language description of the data is still yours to write. Every microchart is `role="img"` with that description generated from the data by default (`describeSeries`); the decorative opt-out is explicit (`summary={false}`). **Chart chrome.** Recharts draws axes, ticks, legends, and tooltips because dashboard surfaces need them. microcharts hard-codes them away because word-sized marks cannot afford them. Neither choice is a defect; they serve different surfaces. ## Reach for Recharts [#reach-for-recharts] * The page is mostly chart: analytics views, report panels, explorable dashboards * You need ticks, legends, brush, zoom, or a tooltip that follows the pointer * Your team already has a Recharts component tree it trusts ## Reach for microcharts [#reach-for-microcharts] * The mark sits in a sentence, a table cell, a tab, a KPI card, or a streamed AI reply * You want static chart SVG out of a React Server Component with nothing to hydrate * You want an accessible name generated from the data without wiring it per chart * Budget matters per mark: <SizeMarketing /> gzip, zero runtime dependencies ## Same app, both libraries [#same-app-both-libraries] This is the common ending, not a compromise: ```tsx // analytics page — Recharts <ResponsiveContainer width="100%" height={240}> <LineChart data={rows}>…</LineChart> </ResponsiveContainer>; // the table that links to it — microcharts import { Sparkline } from "@microcharts/react/sparkline"; <Sparkline data={row.series} width={72} height={16} dots="none" summary={false} />; ``` ## What this page is not saying [#what-this-page-is-not-saying] * Not "Recharts is heavy" — it is correctly sized for the job it does * Not "microcharts can replace your dashboards" — it cannot and does not try * The gzip figures are dated pins, not live measurements ## Next [#next] * [Full chart libraries](/docs/full-chart-libraries) — Recharts and Chart.js in one view * [When to use microcharts](/docs/when-to-use) — the product decision * [microcharts vs Chart.js](/docs/vs-chartjs) * [Performance](/docs/performance) — our own CI receipts # microcharts vs visx — tiny charts comparison (/docs/vs-visx) [visx](https://airbnb.io/visx/) is Airbnb's collection of low-level visualization primitives: shapes, scales, axes, and gradients you compose into your own charts. It is deliberately not a chart library — you are the chart library. microcharts is the opposite bet: finished, opinionated word-sized marks with the design decisions already made. That makes this less a competition than a fork in the road. Both keep bundles lean through per-package (visx) or per-chart (microcharts) imports; the real question is who does the chart design — you or the library. ## The numbers [#the-numbers] <VsVisxTable /> The visx figure is a floor, not a typical cost: `LinePath` plus one scale, before curves, tooltips, or axes. Each `@visx/*` package you add brings its own dependencies (d3 arrives vendored through `@visx/vendor`). ## Where the difference actually shows [#where-the-difference-actually-shows] **Who owns the design.** With visx you decide geometry, padding, label placement, empty-data behavior, negative-value handling, and color semantics per chart — full control, and a real design task at 16 pixels tall. microcharts hard-codes those decisions: areas anchor at zero, direction is never color-alone, labels reserve deterministic gutters, empty and all-null data render documented placeholders. **Who owns accessibility.** A visx `LinePath` renders a bare `<path>` — `role`, `<title>`, and a description of the data are yours to author on every chart you build. Every microchart defaults to `role="img"` with a natural-language summary generated from the data. **Dependency posture.** visx keeps React in control of the DOM and slices d3 into per-package imports — genuinely lighter than shipping all of d3. microcharts goes further for its narrower job: scales, paths, easing, color, and summaries are in-house, so `dependencies: {}` is a CI-enforced invariant. **Edge cases.** NaN, ±Infinity, single points, all-equal series — with primitives, each is your code path. Every microchart documents and tests these in a shared fixture suite. ## Reach for visx [#reach-for-visx] * The visualization is bespoke — no catalog anywhere has your chart * You have design capacity and want d3's power with React's rendering * You are building your organization's own charting layer, at any surface size ## Reach for microcharts [#reach-for-microcharts] * The chart you need already exists in the catalog — <CatalogTotal /> word-sized types, one grammar * You want accessibility, edge cases, and design handled by default * You want static RSC output with zero client JavaScript, at <SizeMarketing /> gzip per chart ## What this page is not saying [#what-this-page-is-not-saying] * Not "visx is heavy" — 16 kB for a floor is honest for hand-built charts, and visx's modularity is well executed * Not "never build your own" — a bespoke visualization deserves primitives * The visx figure is a dated pin for one minimal composition, not a benchmark of visx overall ## Next [#next] * [When to use microcharts](/docs/when-to-use) * [Design notes](/docs/design-notes) — the decisions microcharts makes for you * [microcharts vs Recharts](/docs/vs-recharts) * [Composition](/docs/composition) — placing marks in real surfaces # When to use microcharts (/docs/when-to-use) microcharts is a set of tiny, handcrafted charts for React — built to sit *inside* an interface, where a full chart library would be too heavy and too loud. A trend after a number, a bullet in a KPI, a strip in a table cell, a mark in a streamed reply. One quiet signal, read at a glance. It is not a substitute for [Recharts](https://recharts.org), [Chart.js](https://www.chartjs.org), Nivo, ECharts, or visx. Those libraries draw surfaces that are mostly chart: axes, legends, tooltips, brush, zoom. microcharts draws the opposite: mostly words and UI, with a word-sized mark. Use a full library when the page *is* the chart. Use microcharts when the chart sits inside something you were already reading — or use both in the same product. ## Fit [#fit] | Situation | Fit | | ------------------------------------------------------------------------ | ---------------------------------------------------------------- | | Sparkline, bullet, or delta in prose, a cell, a tab, or a card | **microcharts** | | Static chart from a React Server Component with **zero** client chart JS | **microcharts** (default export) | | A model or agent emitting a chart mid-reply | **microcharts** — see [AI-native](/docs/ai) | | Full Line / Bar / Area with ticks, legend, tooltip, brush | **Recharts, Chart.js, …** | | Dense Canvas series, Chart.js plugins, analyst dashboards | **Chart.js** (or similar) | | One library for every chart in the product | Usually a **full** library; add microcharts for the inline marks | ## What this library refuses [#what-this-library-refuses] Pie, needle gauges, waffles, and similar shapes fail at word size — they are excluded on purpose. Each has a strictly-better in-catalog replacement (for example [SegmentedBar](/docs/charts/segmented-bar), [Bullet](/docs/charts/bullet), [IconArray](/docs/charts/icon-array)). See the [introduction](/docs). ## Size [#size] Every chart is imported from its own subpath and budget-gated in CI: <SizeMarketing /> gzip, **zero runtime dependencies**, static SVG from an RSC with nothing to hydrate. Accessible by default — `role="img"` with a summary generated from the data. Pinned orientation numbers for Recharts and Chart.js (version, date, method): [Full chart libraries](/docs/full-chart-libraries). Our own receipts: [Performance](/docs/performance). ## Same app, two jobs [#same-app-two-jobs] A product can use Recharts on an analytics page and a Sparkline in the table that links to it. Different import, different budget. ```tsx // dashboard panel — your full chart library <ResponsiveContainer>…</ResponsiveContainer>; // same product, table cell — microcharts import { Sparkline } from "@microcharts/react/sparkline"; <Sparkline data={row.series} width={72} height={16} dots="none" summary={false} />; ``` ## Go deeper [#go-deeper] * [React sparklines](/docs/react-sparklines) — the most common word-sized mark * [Inline charts](/docs/inline-charts) — sentences, cells, KPIs, tabs, RSC * [Full chart libraries](/docs/full-chart-libraries) — Recharts and Chart.js, side by side * Comparing a specific library? [vs Recharts](/docs/vs-recharts) · [vs Chart.js](/docs/vs-chartjs) · [vs react-sparklines](/docs/vs-react-sparklines) · [vs MUI X Sparkline](/docs/vs-mui-x-sparkline) · [vs visx](/docs/vs-visx) * [Quickstart](/docs/quickstart) — install and first chart * [Introduction](/docs) — grammar, catalog, and where they live # ABStrips (/docs/charts/ab-strips) ABStrips answers "did B beat A — and by more than the overlap?". It draws **two graded quantile strips on one shared scale**: a faint p5–95 band, a stronger p25–75 middle half, and a median dot, with row A muted and row B accent. The visible overlap of the two middle halves is the answer — and the overlap number is always in the summary, because an average delta without its spread is how A/B results lie. ```tsx <ABStrips data="{ a: Array.from({ length: 80 }, (_, i) => 130 + ((i * 13) % 44) - 22), b: Array.from({ length: 80 }, (_, i) => 116 + ((i * 13) % 44) - 22), }" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" positive="down" title="Latency A/B" width="260" height="26" /> ``` ## Install [#install] ```tsx import { ABStrips } from "@microcharts/react/ab-strips"; const control = Array.from({ length: 80 }, (_, i) => 130 + ((i * 13) % 44) - 22); const test = Array.from({ length: 80 }, (_, i) => 116 + ((i * 13) % 44) - 22); <ABStrips data={{ a: control, b: test }} positive="down" title="Latency A/B" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — an A/B experiment result in a KPI card, control vs test in an experiments table, any two-sample comparison where the spread matters. * **Avoid for** — a single distribution (BenchmarkStrip) or more than two arms (small multiples). ## Variants [#variants] ```tsx 130 + ((i * 13) % 44) - 22); const test = Array.from({ length: 80 }, (_, i) => 116 + ((i * 13) % 44) - 22); <ABStrips data={{ a: control, b: test }} seriesLabels={["Control", "Test"]} />`" > <span className="inline-flex flex-col gap-2"> <ABStrips data="{ a: Array.from({ length: 80 }, (_, i) => 130 + ((i * 13) % 44) - 22), b: Array.from({ length: 80 }, (_, i) => 116 + ((i * 13) % 44) - 22), }" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" seriesLabels="["Ctrl", "Test"]" title="Labelled" width="240" height="24" /> <ABStrips data="{ a: Array.from({ length: 80 }, (_, i) => 170 + ((i * 13) % 44) - 22), b: Array.from({ length: 80 }, (_, i) => 116 + ((i * 13) % 44) - 22), }" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" positive="down" title="Clearly separated" width="240" height="24" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <ABStrips data="{ a: [], b: [110, 120, 130] }" title="No data" width="220" height="22" /> ``` ```tsx `" > <ABStrips data="{ a: [100, 130, 145], b: Array.from({ length: 80 }, (_, i) => 116 + ((i * 13) % 44) - 22), }" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" title="Small A arm" width="220" height="26" /> ``` Either arm with zero finite values makes the whole comparison unanswerable — no strips draw, and the accessible name reads plainly **"No data."** rather than a comparison against nothing. An arm with fewer than 8 points still draws (a small sample is still the honest sample you have); only its outer band changes meaning, from the 5th–95th percentile to the plain min–max, because percentile estimates need more than a handful of points to mean anything. ## Why this default [#why-this-default] Overlap in the summary, because an average delta without spread is how A/B results lie. The strips are mandatory context — it never degrades to a bare mean bar — and the delta label never appears without the distributions behind it. When the middle halves fully overlap the summary says "no clear difference"; when they're disjoint it says "clearly separated"; and an arm with fewer than 8 points falls back to a min–max band. ## Accessibility [#accessibility] The accessible name states both medians, the delta, and the overlap — **"Test median 115 ms vs Ctrl 129 ms (-11%); middle halves overlap 35%."**. The interactive entry roves the rows (↑/↓) and the quantile edges (←/→): the median announces the delta vs the other arm, other edges announce the percentile. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ a: number[]; b: number[] }` | The two arms — raw samples, not summaries. | | `seriesLabels` | `[string, string]` | Row identities for the gutter tags + summary (default ['A', 'B']). | | `positive` | `"up" \| "down"` | Which direction of the B−A delta reads as good (colors the delta). | | `label` | `"delta" \| "none"` | Signed median delta in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # ActivityGrid (/docs/charts/activity-grid) ActivityGrid maps ordered values onto a grid of cells, each shaded by intensity. It's the contribution-graph shape: cadence, streaks, and seasonality, readable at a glance. ```tsx `" > <ActivityGrid data="[0, 1, 2, 1, 3, 4, 2, 0, 1, 3, 2, 4, 3, 1, 0, 2, 4, 3, 2, 1, 3, 0, 2, 3, 4, 1, 2, 0]" cell="11" title="Commit activity" /> ``` ## Install [#install] ```tsx import { ActivityGrid } from "@microcharts/react/activity-grid"; <ActivityGrid data={commits} title="Commits" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — daily activity, streaks and cadence, seasonality at a glance. * **Avoid for** — exact values, or precise comparison between two individual cells. Color intensity is deliberately approximate; pair it with a number when precision matters. ## Sizing [#sizing] ActivityGrid sizes from `cell` — the edge length of one square in viewBox units. Bump it to scale the whole grid, or drive the width from CSS to fill a container; the viewBox keeps the grid's aspect ratio. ## Variants [#variants] `layout="strip"` collapses to a single row for inline use. ```tsx <ActivityGrid data={commits.slice(0, 12)} layout="strip" />`" > <span className="inline-flex flex-col gap-3"> <ActivityGrid data="[0, 1, 2, 1, 3, 4, 2, 0, 1, 3, 2, 4, 3, 1, 0, 2, 4, 3, 2, 1]" cell="12" title="Grid" /> <ActivityGrid data="[0, 1, 2, 1, 3, 4, 2, 0, 1, 3, 2, 4]" layout="strip" cell="12" title="Strip" /> </span> ``` `shape` swaps the cell mark — same data, same levels, different voice: `"round"` for friendlier product surfaces, `"dot"` adds breathing room in dense strips. ```tsx <ActivityGrid data={commits.slice(0, 12)} layout="strip" shape="dot" />`" > <span className="inline-flex flex-col gap-3"> <ActivityGrid data="[0, 1, 2, 1, 3, 4, 2, 0, 1, 3, 2, 4, 3, 1, 0, 2, 4, 3, 2, 1]" shape="round" cell="12" title="Round cells" /> <ActivityGrid data="[0, 1, 2, 1, 3, 4, 2, 0, 1, 3, 2, 4]" layout="strip" shape="dot" cell="12" title="Dot strip" /> </span> ``` `anchor` aligns the grid to the real calendar: the first column pads down to the weekday of the given day (UTC), so rows read as weekdays — Monday first by default (`weekStart={0}` for Sunday). ```tsx `" > <ActivityGrid data="[2, 3, 1, 4, 2, 0, 1, 3, 2, 4, 3, 1, 0, 2, 4, 3, 2, 1]" anchor="1970-01-01" cell="12" title="Week-aligned" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <ActivityGrid data="[]" title="No history" cell="12" /> ``` ```tsx `"> <ActivityGrid data="[0, 0, 0, 0, 0, 0, 0]" title="Quiet week" cell="12" /> ``` ```tsx `"> <ActivityGrid data="[3]" title="One day" cell="12" /> ``` ## Why this default [#why-this-default] Five levels (the empty track plus four intensity steps) matches the five steps HeatCell and HeatStrip default to, and the four intensity steps share their exact opacity ramp — one calibration means "how intense" reads the same across the library, and a reader never has to relearn a color scale per chart. Only level 0 differs: here it is a faint empty track, because an activity slot with no activity is genuinely empty, not a bottom-of-scale value. Levels are discrete, never a continuous gradient: a continuous ramp implies precision a handful of pixels can't actually deliver, and discrete bins are honest about that. Monday-first weeks (`weekStart={1}`) match the ISO calendar most teams already track cadence against; `weekStart={0}` switches to Sunday-first without touching the data. Column-major fill (each column is a week, top-to-bottom) is what makes the grid read as a calendar instead of an arbitrary sequence of cells. ## Accessibility [#accessibility] Intensity is a color channel, so ActivityGrid always pairs it with a numeric summary of its total and peak — the information survives forced-colors and color-blind viewing. The interactive entry adds 2-D arrow-key navigation, announcing each cell's value as you move. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Ordered values, one per cell. | | `layout` | `"grid" \| "strip"` | 7-row calendar or single strip. | | `shape` | `"square" \| "round" \| "dot"` | Cell mark: crisp square, soft corners, or padded dot. | | `anchor` | `string \| Date` | First slot's calendar day (UTC) — pads the first column so weekday rows align. | | `weekStart` | `0 \| 1` | Start of week for anchor alignment (0 Sunday, 1 Monday). | | `cell` | `number` | Cell edge length in viewBox units. | | `domain` | `[number, number]` | Explicit range for level bucketing. | | `title` | `string` | Accessible name; joins the auto summary. | | `summary` | `string \| false` | Override or disable the auto summary. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # BalanceBeam (/docs/charts/balance-beam) BalanceBeam answers "which of two sides outweighs, and roughly by how much?" A beam tilts toward the heavier side; the direction is instant and the angle grows with the imbalance, but it **saturates** — read it as direction plus rough magnitude, not an exact ratio. The two weights are area-true (their area, not their width, is proportional to value). For a precise comparison, reach for `PairedBars` or `Delta`; this is for the glance. ```tsx <BalanceBeam data="[ { label: "Inflow", value: 620 }, { label: "Outflow", value: 480 }, ]" label="values" title="Cash flow" width="80" height="30" /> ``` ## Install [#install] ```tsx import { BalanceBeam } from "@microcharts/react/balance-beam"; <BalanceBeam data={[{ label: "Inflow", value: 620 }, { label: "Outflow", value: 480 }]} /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a buy vs sell or in vs out read in a sentence, a pro vs con weight in a KPI card, or an A-vs-B pair where direction is the story. * **Avoid for** — exact ratios (PairedBars / Delta), more than two items (MiniBar), or trends. ## Variants [#variants] ```tsx <BalanceBeam data={[{ label: "A", value: 500 }, { label: "B", value: 500 }]} />`" > <span className="inline-flex gap-6 items-center"> <BalanceBeam data="[ { label: "Inflow", value: 620 }, { label: "Outflow", value: 480 }, ]" shape="round" label="values" width="90" height="34" /> <BalanceBeam data="[ { label: "A", value: 500 }, { label: "B", value: 500 }, ]" width="70" height="28" /> </span> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, both the announced values and the in-chart numerals (`label="values"`) follow that locale's own grouping and decimal marks. ```tsx `" > <BalanceBeam data="[ { label: "Inflow", value: 62000 }, { label: "Outflow", value: 48000 }, ]" label="values" format="{ maximumFractionDigits: 0 }" locale="de-DE" width="90" height="34" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <BalanceBeam data="[ { label: "A", value: 500 }, { label: "B", value: 500 }, ]" width="70" height="28" /> ``` ```tsx `"> <BalanceBeam data="[ { label: "A", value: 0 }, { label: "B", value: 0 }, ]" width="70" height="28" /> ``` Equal values level the beam and report **"balanced"** rather than picking an arbitrary heavier side. Two zeros are the same case — the beam stays level and both weights shrink to nothing, which is honest: there is nothing to weigh. ## Why this default [#why-this-default] Ratio mode is the default because most two-sided comparisons are share-of-whole questions, and square weights are the default because circles under-read area at this size. The tilt saturates at `maxTilt` degrees — a deliberate honesty choice: past a point, a steeper beam would imply a precision the eye can't extract, so the angle levels off. Direction and rough magnitude always agree, and the two channels (tilt and weight area) never disagree. For same-scale rows that should tilt comparably, `mode="difference"` scales the imbalance by a shared `domain`. ## Accessibility [#accessibility] The accessible name states both sides and the winner — **"Inflow 620 vs Outflow 480; Inflow heavier."** — or "…; balanced." when they match. The interactive entry eases the beam to its new tilt, reveals a side's value on hover or ←/→, and announces when the heavier side flips. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `[{label,value},{label,value}]` | Exactly two items. | | `maxTilt` | `number` | Degrees at full saturation (default 12). | | `shape` | `"square" \| "round"` | Weight shape (default square). | | `mode` | `"ratio" \| "difference"` | ratio = share-of-whole; difference = absolute, scaled by domain. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # BenchmarkStrip (/docs/charts/benchmark-strip) BenchmarkStrip answers "is this value normal for its peer group?". A focal dot sits on a common scale against the peers' own **empirical** quantile bands — never a fitted distribution. There is no axis: the band is the reference frame. Small samples fall back to min–max so tail quantiles are never fiction. ```tsx `" > <BenchmarkStrip data="[ 180, 201, 237, 286, 341, 396, 443, 394, 412, 413, 398, 372, 340, 310, 205, 196, 205, 230, 271, 322, 378, 347, 391, 421, 434, 430, 412, 383, 268, 239, 221, 218, 231, 261, 306, 275, 331, 382, 422, 447, 455, 447, ]" value="312" title="Latency vs peers" width="240" height="16" /> ``` ## Install [#install] ```tsx import { BenchmarkStrip } from "@microcharts/react/benchmark-strip"; <BenchmarkStrip data={peerLatencies} value={312} format={{ style: "unit", unit: "millisecond" }} title="Latency vs peers" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a value against its cohort, per-row peer comparison in tables, SLA context. * **Avoid for** — a single trend (Sparkline) or two groups head-to-head (ABStrips). ## Variants [#variants] ```tsx // 42 peer latencies (ms) const peerLatencies = [ 180, 201, 237, 286, 341, 396, 443, 394, 412, 413, 398, 372, 340, 310, 205, 196, 205, 230, 271, 322, 378, 347, 391, 421, 434, 430, 412, 383, 268, 239, 221, 218, 231, 261, 306, 275, 331, 382, 422, 447, 455, 447, ]; <BenchmarkStrip data={peerLatencies} value={312} label="value" />`" > <span className="inline-flex flex-col gap-1.5"> <BenchmarkStrip data="[210, 260, 300, 340, 410]" value="300" range="minmax" title="Min–max" width="200" height="14" /> <BenchmarkStrip data="[ 180, 201, 237, 286, 341, 396, 443, 394, 412, 413, 398, 372, 340, 310, 205, 196, 205, 230, 271, 322, 378, 347, 391, 421, 434, 430, 412, 383, 268, 239, 221, 218, 231, 261, 306, 275, 331, 382, 422, 447, 455, 447, ]" value="312" label="value" title="Value label" width="200" height="14" /> </span> ``` ```tsx `" > <BenchmarkStrip data="[1080, 1180, 1220, 1360, 1440]" value="1240" label="value" format="{ maximumFractionDigits: 0 }" locale="de-DE" title="Localized value" width="200" height="16" /> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, both the right-gutter label and the accessible summary's numbers follow that locale's own grouping and decimal marks: the value above reads "1.240" in German, not "1,240". ## Edge cases [#edge-cases] ```tsx `" > <BenchmarkStrip data="[210, 260, 300, 340, 410]" value="300" title="5 peers" width="200" height="16" /> ``` ```tsx `"> <BenchmarkStrip data="[50, 50, 50, 50, 50, 50, 50, 50]" value="52" title="Flat cohort" width="200" height="16" /> ``` ```tsx `" > <BenchmarkStrip data="[180, 250, 300, 350, 420]" value="520" domain="[150, 400]" title="Clamped" width="200" height="16" /> ``` ## Why this default [#why-this-default] Bands come from the peers' own empirical quantiles, never a fitted distribution — the strip never implies a normal curve that the data doesn't back up. There is no axis: the band itself is the reference frame, so the focal dot's position against it is the whole read. Below 8 peers, tail quantiles (p5/p95) are statistically unreliable, so the outer band falls back to the observed min–max automatically — a deliberate honesty trade the `range` prop can also force at any sample size. A value that falls outside the plotted domain clamps to the edge and draws a small wedge rather than silently disappearing. ## Accessibility [#accessibility] The accessible name states the value, its percentile, the peer count, and the middle-half interval — **"312 — 43rd percentile of 42 peers (middle half 244.5–408.5)."** A flat cohort states it plainly instead: "52 — all 8 peers at 50." The interactive entry roves the five quantile edges with ←/→, announcing each edge's name and value (e.g. "p75: 408.5."). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Peer values. | | `value` (required) | `number` | The focal reading. | | `range` | `"p5p95" \| "minmax"` | Outer band; minmax for small samples. | | `label` | `"value" \| "percentile" \| "none"` | What the right gutter states (default percentile). | | `positive` | `"up" \| "down"` | Which side of the band is good (colors the focal dot). | | `median` | `boolean` | Center tick (default true). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # BiasStrip (/docs/charts/bias-strip) BiasStrip answers "do two ways of measuring the same thing systematically disagree?" — the agreement story a scatter can't tell. Each dot is one pair placed at its mean and its difference; the dashed line is perfect agreement, the accent line is the measured bias, and the faint band is the limits of agreement. Dots render at 75% opacity so overplot reads as density, and pairs beyond the limits are enlarged and re-inked so outliers read on shape, not color alone. ```tsx <span className="text-lg"> {"Device and reference "} <BiasStrip data="Array.from({ length: 20 }, (_, i) => ({ a: i + [1.8, 2.4, 1.5, 2.9, 2.1, 1.2, 2.6, 3.0, 1.9, 2.3, 6.5, 2.0, 1.7, 2.8, 2.2, -1.5, 2.5, 1.6, 2.7, 2.0][i], b: i, }))" title="Device vs reference" style="{ width: "3.4em", height: "1.9em" }" /> {" agree, +2 bias."} </span> ``` ## Install [#install] ```tsx import { BiasStrip } from "@microcharts/react/bias-strip"; <BiasStrip data={pairs} title="Device vs reference" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — checking whether a new instrument, method, or model agrees with a reference; instrument drift in a KPI card. * **Avoid for** — unpaired samples (use MicroScatter) or a single time series (Sparkline). A correlation plot answers "do these move together?" — but two methods can correlate perfectly and still disagree by a constant offset. BiasStrip is built for that offset: it plots the difference, so a bias jumps off the zero line where a scatter would hide it on the diagonal. ## Variants [#variants] ```tsx `" > <BiasStrip data="Array.from({ length: 20 }, (_, i) => ({ a: i + [1.8, 2.4, 1.5, 2.9, 2.1, 1.2, 2.6, 3.0, 1.9, 2.3, 6.5, 2.0, 1.7, 2.8, 2.2, -1.5, 2.5, 1.6, 2.7, 2.0][i], b: i, }))" limits="2.58" title="99% limits" style="{ width: 150, height: 84 }" /> ``` ```tsx `"> <BiasStrip data="Array.from({ length: 20 }, (_, i) => ({ a: i + [1.8, 2.4, 1.5, 2.9, 2.1, 1.2, 2.6, 3.0, 1.9, 2.3, 6.5, 2.0, 1.7, 2.8, 2.2, -1.5, 2.5, 1.6, 2.7, 2.0][i], b: i, }))" label="none" title="No caption" style="{ width: 150, height: 84 }" /> ``` ```tsx `"> <BiasStrip data="Array.from({ length: 20 }, (_, i) => ({ a: i + [1.8, 2.4, 1.5, 2.9, 2.1, 1.2, 2.6, 3.0, 1.9, 2.3, 6.5, 2.0, 1.7, 2.8, 2.2, -1.5, 2.5, 1.6, 2.7, 2.0][i], b: i, }))" r="2.5" title="Bigger dots" style="{ width: 150, height: 84 }" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <BiasStrip data="[]" title="No pairs" style="{ width: 120, height: 64 }" /> ``` ```tsx `"> <BiasStrip data="[ { a: 2, b: 0 }, { a: 3, b: 1 }, { a: 4, b: 2 }, { a: 5, b: 3 }, ]" title="Four pairs" style="{ width: 120, height: 64 }" /> ``` ```tsx `"> <BiasStrip data="[ { a: 20, b: 20 }, { a: 21, b: 21 }, { a: 22, b: 22 }, { a: 23, b: 23 }, { a: 24, b: 24 }, { a: 25, b: 25 }, ]" title="Perfect agreement" style="{ width: 120, height: 64 }" /> ``` Empty data draws just the frame with "No data." as the summary. Under 5 pairs the limits aren't meaningful, so the band and bias line drop out and only the dots and the zero reference remain — the mean difference is still stated in the summary. When the two methods agree perfectly the band collapses to a hair around the zero line rather than vanishing, so "nothing to see" still reads as a deliberate, measured result. Pairs with a non-finite value are dropped before the stats and the count; past 40 pairs the dots are uniformly downsampled for display while the bias and limits still use every pair. ## Why this default [#why-this-default] The y-axis is symmetric about zero so perfect agreement is always the visual center: a systematic offset then reads as the whole cloud drifting up or down, which is exactly the decision the chart exists to surface. The band is the classic ±1.96σ limits of agreement, and `limits` widens or tightens it (2.58 for \~99%) without ever redefining what the marks mean. Under five pairs the chart makes no interval claim at all — too little evidence to draw one honestly. ## Accessibility [#accessibility] The accessible name is the bias plus the evidence-backed agreement share — **"Bias +2.21 across 20 pairs; 90% within the limits of agreement."** — or the shorter **"Bias +2 across 4 pairs."** when there are too few pairs to draw limits. Localizing carries the number format through: with `locale="de-DE"` the same chart reads **"Bias +2,21 across 20 pairs; 90% within the limits of agreement."** The interactive entry steps pairs ordered by mean and announces each pair's mean, difference, and whether it clears the limits. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ a; b }[]` | Paired measurements. | | `limits` | `number` | k in bias ± k·σ (default 1.96 ≈ 95% limits of agreement). | | `label` | `"bias" \| "none"` | Seat-gated bias caption (default) or hidden. | | `r` | `number` | Base dot radius, clamped [1, 3]. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # BreathingDot (/docs/charts/breathing-dot) BreathingDot answers "how loaded is the system right now?" as an ambient signal. In the interactive entry the dot **pulses** — slow and small when calm, fast and large when strained — so you feel the state without reading a number. The static frame is a real chart with zero JavaScript: a core dot colored by band, and a ring whose distance from the core is the level. This is a low-precision ambient read; for an exact figure reach for `Progress` or `Sparkline`. ```tsx <BreathingDot value="0.42" title="Load" size="40" /> ``` ## Install [#install] ```tsx import { BreathingDot } from "@microcharts/react/breathing-dot"; <BreathingDot value={0.42} title="Load" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## Motion, and reduced motion [#motion-and-reduced-motion] The pulse **is** the encoding — its rate and amplitude are snapped to three named bands (calm, elevated, strained), so the motion is readable, not decorative. This is the deliberate exception to the no-looping-animation rule, allowed only because the loop parameter (the rate) is the datum. The animation is gated on two things: it pauses when the dot scrolls off-screen (a shared observer), and it never runs at all under `prefers-reduced-motion` — reduced-motion readers get exactly the static frame, where the ring's distance from the core already carries the level. The band is announced through a polite live region only when it changes, never on every pulse. ## When to use it [#when-to-use-it] * **Good for** — an ambient "how strained is it right now" read, a live status dot in a header or KPI card, or per-node load in a dense table. * **Avoid for** — an exact load figure (`Progress`, `Sparkline`), discrete events (`HeartbeatBlip`), or a trend over time (`Sparkline`). ## Sizing [#sizing] One `size` prop, in viewBox units, sets the glyph box — it defaults to `16`, about the height of a line of body text. There is no separate `width`/`height`: the dot is square, and the rendered box widens only by the gutter a `label` reserves. `fontSize` follows `size` unless you set it. ## Variants [#variants] ```tsx <BreathingDot value={0.42} label="value" />`" > <span className="inline-flex gap-6 items-center"> <BreathingDot value="0.2" size="28" /> <BreathingDot value="0.65" size="28" /> <BreathingDot value="0.92" label="value" size="28" /> <BreathingDot value="null" size="28" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <BreathingDot value="null" size="28" /> ``` ```tsx `"> <BreathingDot value="1.4" label="value" size="28" /> ``` ```tsx `"> <BreathingDot value="Number.NaN" size="28" /> ``` ```tsx `"> <BreathingDot value="0.723" label="value" locale="de-DE" size="28" /> ``` `format`/`locale` reach the `label="value"` percent numeral — always a whole percent, so a locale mostly changes digit shapes here, not grouping or decimals. The band words in the accessible summary ("calm" / "elevated" / "strained") stay in `strings` (`BreathingDotStrings`), not the number formatter. ## Why this default [#why-this-default] Three bands, because ambient motion supports about three discriminable states — more would be false precision. The band color is always doubled: by the ring offset in the static frame and by the pulse rate in motion, so the state never rests on color alone. When the value is unknown (`null` or `NaN`) the dot goes gray, drops its ring, and **never pulses** — an unknown system must not look calm. The boundary with `HeartbeatBlip`: a continuous level is a BreathingDot; discrete arriving events are a HeartbeatBlip. ## Accessibility [#accessibility] The accessible name is the level and its band word — **"Load 20% — calm."** — or **"Load unknown."** when the value is missing. The band color is never the only signal (ring offset and pulse rate double it), motion is fully gated on `prefers-reduced-motion`, and the live region announces band changes only. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | Level 0–1 (clamped). null / NaN → unknown. | | `thresholds` | `[number, number]` | calm / elevated / strained edges (default [0.5, 0.8]). | | `label` | `"value" \| "none"` | Percent numeral beside the dot. | 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](/docs/quickstart#the-shared-grammar). # BubbleRow (/docs/charts/bubble-row) BubbleRow answers "roughly how do these few magnitudes compare?" with physical presence — a row of circles whose **area** (not width) is proportional to value. Area is the weakest common channel, so this is the catalog's honest low-precision exemplar: **for a precise comparison, use `MiniBar`.** The value numerals are on by default, because a low-precision channel owes the reader the number. ```tsx <BubbleRow data="[ { label: "EMEA", value: 1240 }, { label: "AMER", value: 890 }, { label: "APAC", value: 560 }, { label: "LATAM", value: 210 }, ]" title="Market size" height="36" /> ``` ## Install [#install] ```tsx import { BubbleRow } from "@microcharts/react/bubble-row"; <BubbleRow data={regions} title="Market size" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a few magnitudes with physical presence in a sentence, a market-size or segment impression in a KPI card, or an editorial callout where the number is printed too. * **Avoid for** — precise comparison (that's `MiniBar`), trends (Sparkline), or more than about eight items. ## Variants [#variants] ```tsx <BubbleRow data={regions} label="both" />`" > <span className="inline-flex flex-col gap-4"> <BubbleRow data="[ { label: "EMEA", value: 1240 }, { label: "AMER", value: 890 }, { label: "APAC", value: 560 }, { label: "LATAM", value: 210 }, ]" align="baseline" height="36" /> <BubbleRow data="[ { label: "EMEA", value: 1240 }, { label: "AMER", value: 890 }, { label: "APAC", value: 560 }, { label: "LATAM", value: 210 }, ]" label="both" height="36" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <BubbleRow data="[]" title="No regions" height="30" /> ``` ```tsx `"> <BubbleRow data="[ { label: "EMEA", value: 1240 }, { label: "AMER", value: null }, ]" title="Missing AMER figure" height="30" /> ``` Empty data draws just the frame with "No data." as the summary. A `null` value still holds its place with a small presence ring (never a zero-radius void, and never skipped from the row) but drops its numeral — a missing figure is visibly present yet explicitly unlabeled, never faked as a zero. ## Why this default [#why-this-default] Value numerals are on by default because area lies quietly — a bubble twice the diameter is four times the area, and the eye can't reliably invert that, so the number keeps the read honest. The radius is always `r ∝ √value` with no exceptions; a linear-radius map would be a roughly squared lie. There is no sorting prop: the order is your data's order, because reordering is your statement, not the chart's. The LOW precision rating and the MiniBar steer are printed in the catalog, the machine `/catalog.json`, and this page's header — BubbleRow is the catalog's worked example of an honest low-precision admission. ## Accessibility [#accessibility] The accessible name names the extremes — **"4 items; largest EMEA at 1,240, smallest LATAM at 210."** The interactive entry roves the bubbles with ←/→ (or hover), announcing each one's exact value — **"EMEA: 1,240."** — the number the area itself can't carry. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label, value }[]` | A few non-negative magnitudes. | | `align` | `"center" \| "baseline"` | center (specimen) or baseline (weights on a shelf). | | `label` | `"value" \| "both" \| "none"` | value (default), both, or none. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Bullet (/docs/charts/bullet) Bullet compares one measured value to a target, against a backdrop of qualitative bands (poor / okay / good). It answers "are we there yet?" in a single row — ideal for progress, SLAs, budgets, and quotas. ```tsx <Bullet value="72" target="80" bands="[50, 90]" width="200" height="22" title="Quota attainment" /> ``` ## Install [#install] ```tsx import { Bullet } from "@microcharts/react/bullet"; <Bullet value={72} target={80} bands={[50, 90]} title="Quota" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — progress to a goal, a value against a target, KPIs with thresholds. * **Avoid for** — trends over time (use [Sparkline](/docs/charts/sparkline)) or distributions. ## Sizing [#sizing] `width` and `height` are viewBox units that also set the rendered pixel box — a bullet reads best wide and short. Omit them and drive the width from CSS to fill a table cell or card column; the viewBox keeps the aspect ratio. ## Variants [#variants] ```tsx `"> <Bullet value="72" target="80" bands="[50, 90]" width="220" height="22" title="Behind target" /> ``` ```tsx `"> <Bullet value="94" target="80" bands="[50, 90]" width="220" height="22" title="Ahead of target" /> ``` ```tsx `"> <Bullet value="38" target="80" width="220" height="22" title="Measure and target only" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <Bullet value="120" target="80" domain="[0, 100]" width="220" height="22" title="Over the domain" /> ``` ```tsx `" > <Bullet value="NaN" target="80" bands="[50, 90]" width="220" height="22" title="No data" /> ``` ## Why this default [#why-this-default] The qualitative bands sit lowest and graduate in shade by step, because they are context, not the answer — the measure bar has to read as the loudest mark on the row. The target is a tick, not a second bar: a distinct shape at a distinct position so "value vs target" survives grayscale print and never depends on the two colors staying apart. The measure bar itself is a thin band centered in the track (Few's proportion, not a full-height fill) so the bands stay legible on both sides of it. ## Accessibility [#accessibility] Bullet announces its value against its target — **"72 of 80 target."**. No color is required to read whether the target was met: the measure's length and the target tick encode it by position, and the qualitative bands sit behind them. The interactive entry reads the value and target on hover and focus. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The measured value. | | `target` | `number` | Target tick to compare against. | | `bands` | `number[]` | Ascending qualitative thresholds. | | `domain` | `[number, number]` | Explicit [0, max]; auto-fit otherwise. | | `label` | `"none" \| "value" \| "target" \| "both"` | Value/target readout in a right gutter (default none). | | `title` | `string` | Accessible name; joins the auto summary. | | `summary` | `string \| false` | Override or disable the auto summary. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # BumpStrip (/docs/charts/bump-strip) BumpStrip answers "where do we rank, and which way is it moving?" — position on an inverted ordinal scale, so #1 sits on top and climbing draws upward. Ranks are not values: Sparkline would lie about the distance between #2 and #3. ```tsx <BumpStrip data="[5, 5, 4, 4, 4, 3, 2, 2, 3, 2, 1, 1]" title="Category rank" width="220" height="26" /> ``` ## Install [#install] ```tsx import { BumpStrip } from "@microcharts/react/bump-strip"; <BumpStrip data={weeklyRanks} title="Category rank" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — leaderboard rows, category-rank trends in KPI cards. * **Avoid for** — continuous values (Sparkline), or more than \~15 rank levels. ## Variants [#variants] ```tsx `" > <BumpStrip data="[2, null, null, 3, 1, 1]" title="With unranked weeks" width="220" height="26" /> ``` ```tsx `"> <BumpStrip data="[8, 7, 7, 6, 4, 4, 3, 3, 2, 2, 2, 1]" maxRank="10" title="Fixed 10-rank band" width="220" height="26" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <BumpStrip data="[3]" maxRank="5" title="One period" width="140" height="26" /> ``` ```tsx `" > <BumpStrip data="[null, null, null]" title="No ranked periods" width="140" height="26" /> ``` ```tsx `" > <BumpStrip data="[3, 3, 3, 3, 3]" title="Steady at #3" width="140" height="26" /> ``` A single ranked period draws its two end labels with no visible line — there is no trajectory to show yet. An all-`null` series renders the frame with neither line nor labels; the accessible name reports it directly rather than describing a blank chart. A flat run (rank never changes) draws a level line with zero change dots, since `dots="changes"` only marks the periods where rank actually moved. ## Why this default [#why-this-default] Change dots mark only the periods where rank actually moved — flat runs stay quiet, so the eye lands on the transitions. End labels ("#5" → "#1") anchor the ordinal read without an axis. ## Accessibility [#accessibility] The accessible name is the full trajectory — **"From #8 to #1 over 12 weeks; best #1."** The interactive entry steps the periods (**"Week 7 of 12: #2."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | 1-based integer ranks; null = unranked period (gap). | | `maxRank` | `number` | Fix the band so small multiples share a rank scale. | | `dots` | `"changes" \| "none"` | Mark the moments rank actually moved. | | `label` | `"ends" \| "last" \| "none"` | "#5" → "#1" endpoint labels. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # BurnChart (/docs/charts/burn-chart) BurnChart answers "will we finish on time?". It draws the **plan** line (dashed, full length to the deadline), the **actual** line to today, and a **dotted projection** whose slope is a plain linear fit over the last few actual points — provisional by construction, never a smoothed or optimistic curve. The gap label states the signed schedule landing, because "will we finish" is a number, not a vibe. ```tsx `" > <BurnChart data="{ plan: [40, 36, 32, 28, 24, 20, 16, 12, 8, 4, 0], actual: [40, 35, 31, 27, 24, 21] }" label="gap" title="Sprint 12" width="260" height="30" /> ``` ## Install [#install] ```tsx import { BurnChart } from "@microcharts/react/burn-chart"; <BurnChart data={{ plan, actual }} title="Sprint 12" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a sprint burndown in a tab header, will-we-finish in a KPI card, plan vs actual with a projected landing. * **Avoid for** — a single progress number (Progress) or a plain series (Sparkline). ## Variants [#variants] ```tsx <BurnChart data={{ plan: [0, 4, 8, 12, 16, 20, 24, 28, 32, 36, 40], actual: [0, 5, 9, 13, 16, 19] }} mode="up" />`" > <span className="inline-flex flex-col gap-1.5"> <BurnChart data="{ plan: [40, 36, 32, 28, 24, 20, 16, 12, 8, 4, 0], actual: [40, 35, 31, 27, 24, 21] }" projection="false" title="Retrospective" width="220" height="28" /> <BurnChart data="{ plan: [0, 4, 8, 12, 16, 20, 24, 28, 32, 36, 40], actual: [0, 5, 9, 13, 16, 19] }" mode="up" title="Burn-up to scope" width="220" height="28" /> </span> ``` ```tsx `" > <BurnChart data="{ plan: [4000, 3200, 2400, 1600, 800, 0], actual: [4000, 3400, 2800, 2300] }" locale="de-DE" title="Localized point counts" width="220" height="28" /> ``` With a `locale`, the accessible summary's numbers follow that locale's own grouping — "2.300" in German, not "2,300". ## Edge cases [#edge-cases] ```tsx `" > <BurnChart data="{ plan: [], actual: [40, 35, 31, 27, 24, 21] }" title="No plan recorded" width="220" height="28" /> ``` ```tsx `" > <BurnChart data="{ plan: [40, 36, 32, 28, 24, 20], actual: [40, 40, 40, 40] }" title="Stalled" width="220" height="28" /> ``` ```tsx `"> <BurnChart data="{ plan: [40, 36, 32, 28, 24, 20], actual: [40] }" title="Day one" width="220" height="28" /> ``` With no plan (`plan: []`), the projection still runs — the fitted slope only needs `actual` — but there's nothing to compare it to, so the summary drops the "vs planned" clause. A stalled burn (`actual` flat) never reaches zero, so `finishes` is `false` and the summary states that plainly rather than extrapolating a fake landing. A single `actual` point draws no projection at all (the fit needs at least two). ## Why this default [#why-this-default] The gap label, because "will we finish" is a number, not a vibe. History is drawn solid and exact; the projection is dotted, muted, and computed as a linear fit over the last `max(2, ⌈actual/3⌉)` actual points — a stated method, never an optimistic hand-drawn curve. When the recent burn flattens, the projection never reaches zero and the summary says so outright ("not finishing at the current pace"), rather than implying a landing that isn't coming. ## Accessibility [#accessibility] The accessible name states progress against the plan and the projected landing — **"6 of 11 days in: 19 points done vs 20 planned — projected to finish 2 days late."**. The interactive entry steps the days; history announces actual vs plan, and the dotted region announces the projection. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ plan: number[]; actual: number[] }` | Remaining work per period (mode='down') or completed (mode='up'). | | `mode` | `"down" \| "up"` | Burn-down (remaining → 0, default) or burn-up (done → scope). | | `projection` | `boolean` | The dotted extrapolation to the deadline (default true). | | `work` | `string` | Work-unit noun for the summary and readout. Defaults to `strings.burnWork` ('points' in EN), so a localized bundle replaces it. | | `unit` | `string` | Period noun for the summary and gap label (default 'day'). | | `label` | `"gap" \| "none"` | Signed schedule landing vs the deadline in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # CalendarStrip (/docs/charts/calendar-strip) CalendarStrip answers "what did the last few weeks actually look like, day by day?" — week-aligned recent activity where real calendar position matters. Weekday rhythm is the read; for longer ordinal histories, use ActivityGrid. ```tsx <CalendarStrip data="Array.from({ length: 18 }, (_, i) => ({ date: `2026-06-${String(4 + i).padStart(2, "0")}`, value: i % 4 === 3 ? 0 : (i % 7) + 1, }))" end="2026-07-01" title="Deploy cadence" style="{ width: 150, height: 84 }" /> ``` ## Install [#install] ```tsx import { CalendarStrip } from "@microcharts/react/calendar-strip"; <CalendarStrip data={days} end="2026-07-01" title="Deploy cadence" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — habit/deploy cadence in KPI cards, week-aligned recent activity. * **Avoid for** — long ordinal histories (ActivityGrid), exact per-day values (MiniBar). ## Variants [#variants] ```tsx `"> <CalendarStrip data="Array.from({ length: 18 }, (_, i) => ({ date: `2026-06-${String(4 + i).padStart(2, "0")}`, value: i % 4 === 3 ? 0 : (i % 7) + 1, }))" end="2026-07-01" weeks="2" title="Two weeks" style="{ width: 150, height: 42 }" /> ``` ```tsx `"> <CalendarStrip data="Array.from({ length: 18 }, (_, i) => ({ date: `2026-06-${String(4 + i).padStart(2, "0")}`, value: i % 4 === 3 ? 0 : (i % 7) + 1, }))" end="2026-07-01" weekStart="0" title="Sunday start" style="{ width: 150, height: 84 }" /> ``` `cell`/`gap` bump the edge length and spacing directly — grid-sibling parity with ActivityGrid and GardenGrid. ```tsx `"> <CalendarStrip data="Array.from({ length: 18 }, (_, i) => ({ date: `2026-06-${String(4 + i).padStart(2, "0")}`, value: i % 4 === 3 ? 0 : (i % 7) + 1, }))" end="2026-07-01" cell="10" gap="2" title="Larger cells" style="{ width: 200, height: 112 }" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <CalendarStrip data="[]" end="2026-07-01" title="No records" style="{ width: 150, height: 84 }" /> ``` ```tsx `"> <CalendarStrip data="Array.from({ length: 14 }, (_, i) => ({ date: new Date(Date.UTC(2026, 5, 18) + i * 86400000).toISOString().slice(0, 10), value: 0, }))" end="2026-07-01" weeks="2" title="Quiet fortnight" style="{ width: 150, height: 42 }" /> ``` ## Why this default [#why-this-default] Monday start + 4 weeks: one glance covers a month of weekday rhythm without scrolling history. All date math is UTC — the same input renders identically in any host timezone, so SSR output never depends on where the server runs. `end` defaults to today but should be pinned wherever determinism matters. Empty ≠ zero: a day with no record renders as a faint outline, a day with value 0 as a filled track cell — a feed gap never masquerades as a quiet day. Future days are blank, never extrapolated. ## Accessibility [#accessibility] The accessible name counts real days — **"Active 11 of 24 days over 4 weeks."** The interactive entry walks the grid in 2-D and announces real calendar days (**"Thursday, June 11: 0."**, **"Tuesday, June 23: no data."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ date; value }[]` | Date-keyed values; duplicates sum with a dev warning. | | `weeks` | `number` | Window length in whole weeks ending at `end` (default 4). | | `end` | `string \| Date` | Last day of the window (defaults to today UTC — pin it for SSR determinism). | | `weekStart` | `0 \| 1` | Locale start-of-week (default Monday). | | `steps` | `number` | Intensity steps including the zero track (default 5). | | `shape` | `"square" \| "round" \| "dot"` | Shared cell vocabulary. | | `cell` | `number` | Cell edge length in viewBox units (default 7). | | `gap` | `number` | Gap between cells (default 1). | | `dateFormat` | `Intl.DateTimeFormatOptions \| (d: Date) => string` | (interactive) Announced day label (defaults to weekday + month + day, UTC). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # CalibrationStrip (/docs/charts/calibration-strip) CalibrationStrip answers "when this model says 70%, does it happen 70% of the time — and where is there enough data to even ask?". Each bin is a dot at its predicted probability and its observed frequency, read against the identity diagonal, with a quiet support lane underneath. Bins with too little data render open and faded, so a confident-looking dot is never backed by three samples. ```tsx <CalibrationStrip data="[ { predicted: 0.05, observed: 0.05, count: 100 }, { predicted: 0.15, observed: 0.16, count: 90 }, { predicted: 0.25, observed: 0.24, count: 80 }, { predicted: 0.35, observed: 0.36, count: 70 }, { predicted: 0.45, observed: 0.44, count: 60 }, { predicted: 0.55, observed: 0.56, count: 50 }, { predicted: 0.65, observed: 0.63, count: 40 }, { predicted: 0.7, observed: 0.52, count: 30 }, { predicted: 0.85, observed: 0.83, count: 8 }, { predicted: 0.95, observed: 0.9, count: 5 }, ]" title="Model calibration" width="300" height="44" /> ``` ## Install [#install] ```tsx import { CalibrationStrip } from "@microcharts/react/calibration-strip"; <CalibrationStrip data={reliability} title="Model calibration" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — classifier reliability / trust, probability-forecast auditing. * **Avoid for** — a single accuracy number (Delta) or where the errors go ([ConfusionGrid](/docs/charts/confusion-grid)). ## Variants [#variants] ```tsx `" > <CalibrationStrip data="[ { predicted: 0.1, observed: 0.08, count: 90 }, { predicted: 0.3, observed: 0.36, count: 70 }, { predicted: 0.5, observed: 0.44, count: 55 }, { predicted: 0.7, observed: 0.52, count: 30 }, { predicted: 0.9, observed: 0.85, count: 8 }, ]" mode="bars" title="Deviation" width="300" height="40" /> ``` ```tsx `" > <CalibrationStrip data="[ { predicted: 0.2, observed: 0.21, count: 40 }, { predicted: 0.5, observed: 0.44, count: 30 }, { predicted: 0.7, observed: 0.52, count: 30 }, ]" locale="de-DE" title="Localized probabilities" width="200" height="36" /> ``` Nothing visible changes with `locale` — this chart draws no numerals. It localizes the announced numbers: with `locale="de-DE"` the accessible name above reads "3 bins; largest gap at 0,7 predicted (observed 0,52); 0 low-support bins." — the locale's own decimal mark, not "0.7". ## Edge cases [#edge-cases] ```tsx `" > <CalibrationStrip data="[ { predicted: 0.2, observed: 0.21, count: 25 }, { predicted: 0.4, observed: 0.39, count: 25 }, { predicted: 0.6, observed: 0.63, count: 25 }, { predicted: 0.8, observed: 0.79, count: 25 }, ]" title="Well calibrated" width="200" height="36" /> ``` ```tsx `" > <CalibrationStrip data="[ { predicted: 0.3, observed: 0.2, count: 3 }, { predicted: 0.6, observed: 0.7, count: 4 }, { predicted: 0.9, observed: 0.6, count: 3 }, ]" title="Sparse bins" width="200" height="36" /> ``` ## Why this default [#why-this-default] Dots plus an always-on support lane because "how sure" and "based on how much" must travel together — a reliability read without support disclosure is exactly the failure this chart exists to prevent. Low-support bins are drawn open and faded and the count is never disableable. There is deliberately no single-number calibration score (ECE) rendered or announced: one number would hide precisely the per-bin structure the chart exists to show. ## Accessibility [#accessibility] The accessible name reports the worst miscalibration and the support gaps — **"5 bins; largest gap at 0.7 predicted (observed 0.52); 1 low-support bin."** The interactive entry roves the bins with ←/→, announcing each bin's predicted and observed probability and its sample support. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `RawPair[] \| BinnedRow[]` | Raw pairs or pre-binned reliability rows. | | `bins` | `number` | Uniform bin count for raw input. | | `minSupport` | `number` | Below this a bin renders low-confidence. | | `mode` | `"dots" \| "bars"` | Bars draw signed deviation columns. | | `color` | `string` | Accent stroke/fill override. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # ChangePoint (/docs/charts/change-point) ChangePoint answers "when did the behavior change level?". It shades alternating regimes, draws a per-regime mean, and marks the break where one level became another — because a spike means nothing without the regime it broke. The detector is a **documented heuristic, not statistics**; for production anomaly pipelines, pass your own break indices and the chart becomes pure annotation. ```tsx `" > <ChangePoint data="[30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48]" label="delta" title="Error rate" width="200" height="24" /> ``` ## Install [#install] ```tsx import { ChangePoint } from "@microcharts/react/change-point"; <ChangePoint data={errors} label="delta" title="Error rate" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — context for an anomaly, an error rate / latency / cost that stepped to a new level, or annotating a known deploy or incident (pass explicit `breaks`). * **Avoid for** — a gradual trend (Sparkline) or a plain time series with no regime question. ## Variants [#variants] ```tsx <ChangePoint data={[20, 21, 23, 24, 26, 27, 29, 30, 32, 33, 35, 36, 38, 39, 41, 42, 44, 45, 47, 48]} />`" > <span className="inline-flex gap-4 items-center"> <ChangePoint data="[30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48]" breaks="[14]" width="150" height="22" /> <ChangePoint data="[20, 21, 23, 24, 26, 27, 29, 30, 32, 33, 35, 36, 38, 39, 41, 42, 44, 45, 47, 48]" width="150" height="22" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <ChangePoint data="[3000, 3000, 3000, 3000, 3000, 3000, 3000, 5200, 5200, 5200, 5200, 5200, 5200]" label="delta" locale="de-DE" title="Localized regime means" width="200" height="24" /> ``` ```tsx `" > <ChangePoint data="[10, 10, 10, 50, 50, 50]" title="Six points" width="150" height="22" /> ``` ```tsx `"> <ChangePoint data="[42]" title="One point" width="100" height="22" /> ``` With a `locale`, the summary and delta label format their numbers in that locale's own grouping and decimal marks. Auto-detection (`breaks="auto"`) only runs at 8 or more points — a six-point series with an obvious jump still renders as one flat, unbroken regime unless you pass `breaks` explicitly; this is deliberate, since a two-segment fit on that few points is mostly noise. A single point has no line to draw and no break to find; `data={[]}` renders the frame with the "no data" summary and no marks. ## Why this default [#why-this-default] Context for every anomaly — the shading names the regime a value belongs to, and the break marks where the level truly changed, so a reader sees "errors stepped up here" rather than "errors are high". The detector is a **labelled heuristic**: a two-segment mean-shift found by binary segmentation, accepted only when the split both cuts the variance enough and clears an effect-size threshold, so a constant series shows no break. It is a mean-shift test, not a trend test: a steady ramp is still fitted as two regimes (the ramp variant above reports a shift around point 10), so pass `breaks` explicitly when you already know the series is trending rather than stepping. For anomaly pipelines that already know their breakpoints, `breaks={[…]}` turns the detection off and the chart becomes a faithful annotation. ## Accessibility [#accessibility] The accessible name states the shift, the break, the regime means, and what happened after — **"Level shifted up 60% around point 14 (mean 30 → 48); stable since."** — or, with no detected shift, "No clear level shift across N points." The interactive entry steps the points with ←/→ (value + regime) and cycles the breaks with Tab, each announcing its mean shift. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | A single series. | | `breaks` | `"auto" \| number[]` | Explicit indices override the heuristic entirely — the production path. | | `maxItems` | `number` | Max detected breaks (1–3). More regimes stop being glanceable. | | `means` | `boolean` | Per-regime mean hairlines (default true). | | `label` | `"delta" \| "none"` | Signed % across the most recent break, in a gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # CitySkyline (/docs/charts/city-skyline) CitySkyline answers "how do these groups compare on size, and how activated is each?" — two variables in one row. **Height** is the primary, precise channel (zero-anchored bars, like a MiniBar); the **lit-window fraction** is a secondary, low-precision channel you read as "mostly lit, half lit, or dark", not a number. Omit `lit` everywhere and it's a plain, honest bar row. ```tsx `" > <CitySkyline data="[{ label: "Platform", value: 46, lit: 0.7 }, { label: "Core", value: 32, lit: 0.5 }, { label: "Web", value: 28, lit: 0.9 }, { label: "API", value: 40, lit: 0.3 }, { label: "Data", value: 18, lit: 0.6 }]" unit="teams" title="Team sizes" bw="16" gap="6" height="40" /> ``` ## Install [#install] ```tsx import { CitySkyline } from "@microcharts/react/city-skyline"; <CitySkyline data={teams} unit="teams" title="Team sizes" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — team or region size plus an activation read, an org KPI where two variables are the story, or a per-BU comparison with utilization. * **Avoid for** — a single variable (that's `MiniBar`), precise activation reads, or more than about eight groups. ## Variants [#variants] ```tsx ({ label, value }))} /> <CitySkyline data={teams} label="value" />`" > <span className="inline-flex gap-8 items-end"> <CitySkyline data="[ { label: "A", value: 46 }, { label: "B", value: 32 }, { label: "C", value: 40 }, ]" bw="14" gap="5" height="30" /> <CitySkyline data="[ { label: "A", value: 46, lit: 0.7 }, { label: "B", value: 32, lit: 0.4 }, ]" label="value" bw="16" gap="6" height="34" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <CitySkyline data="[ { label: "A", value: 30, lit: 0.8 }, { label: "B", value: 30, lit: 0.4 }, { label: "C", value: 30, lit: 0 }, ]" title="Flat skyline" bw="16" gap="6" height="36" /> ``` ```tsx `" > <CitySkyline data="[ { label: "big", value: 40, lit: 0.8 }, { label: "tiny", value: 2, lit: 0.9 }, ]" title="Secondary channel drops out first" bw="16" gap="6" height="36" /> ``` ## Why this default [#why-this-default] Windows come on when `lit` is present, because the two-variable read is exactly why this beats a `MiniBar`. Heights are always zero-anchored bars; the lit windows are quantized to the window count and filled bottom-up, so the activation reads as a fill level. There is no roofline variation, no antennas, and nothing encoded in building width — width, roof, and ground are constants, because every mark must earn its place. The secondary channel drops out before the primary: a building too short for any window row is a solid tower, and its `lit` still shows in the per-building readout on hover or keyboard focus. ## Accessibility [#accessibility] The accessible name names the count and the tallest — **"3 groups; tallest A at 46."** The interactive entry roves the buildings with ←/→ (or hover), announcing each on its own: on the team demo at the top of this page, Platform reads "Platform: 46; 70% lit." — the size precisely, the activation as a percent. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label, value, lit? }[]` | value = height; lit = 0–1 window fraction. | | `labels` | `boolean` | Category labels under the buildings. | | `ground` | `boolean` | The baseline hairline (default true). | | `label` | `"none" \| "value"` | Numeral above each building. | | `unit` | `string` | Category noun for the summary (default 'groups'). | | `bw` | `number` | Building width in viewBox units (default 9). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # CohortTriangle (/docs/charts/cohort-triangle) CohortTriangle stacks retention cohorts as rows and ages as columns, shading each cell by a discrete retention level. Because newer vintages have been observed for fewer ages, the block takes the classic **triangle** shape — and reading down a column compares every cohort at the **same maturity**, which is where "who retains worst" actually lives. ```tsx <CohortTriangle data="[ { label: "Jan", values: [1, 0.62, 0.48, 0.41, 0.38, 0.37] }, { label: "Feb", values: [1, 0.58, 0.44, 0.38, 0.35] }, { label: "Mar", values: [1, 0.47, 0.36, 0.31] }, { label: "Apr", values: [1, 0.55, 0.42] }, { label: "May", values: [1, 0.52] }, ]" cell="16" unit="month" title="Monthly retention" /> ``` ## Install [#install] ```tsx import { CohortTriangle } from "@microcharts/react/cohort-triangle"; <CohortTriangle data={cohorts} unit="month" title="Monthly retention" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — monthly or weekly cohorts side by side, spotting which vintage decays worst, reading retention at equal maturity in a KPI card. * **Avoid for** — exact per-cell values (color intensity is deliberately approximate; pair it with a number when precision matters), or a single cohort's decay, where [RetentionCurve](/docs/charts/retention-curve) draws the curve directly. ## Sizing [#sizing] CohortTriangle sizes from `cell` — the edge length of one square in viewBox units. Bump it to scale the whole grid; the viewBox keeps the aspect ratio when CSS drives the width. Row labels seat automatically and drop out cleanly below roughly an 8-unit cell. ## Variants [#variants] Row labels are on by default. Turn them off for a dense, glanceable block, or `highlight` one vintage to anchor the equal-maturity comparison. ```tsx <CohortTriangle data={cohorts} labels={false} cell={9} />`" > <span className="inline-flex flex-col gap-3"> <CohortTriangle data="[ { label: "Jan", values: [1, 0.62, 0.48, 0.41, 0.38, 0.37] }, { label: "Feb", values: [1, 0.58, 0.44, 0.38, 0.35] }, { label: "Mar", values: [1, 0.47, 0.36, 0.31] }, { label: "Apr", values: [1, 0.55, 0.42] }, { label: "May", values: [1, 0.52] }, ]" cell="16" unit="month" highlight="Mar" title="Worst vintage ringed" /> <CohortTriangle data="[ { label: "Jan", values: [1, 0.62, 0.48, 0.41, 0.38, 0.37] }, { label: "Feb", values: [1, 0.58, 0.44, 0.38, 0.35] }, { label: "Mar", values: [1, 0.47, 0.36, 0.31] }, { label: "Apr", values: [1, 0.55, 0.42] }, { label: "May", values: [1, 0.52] }, ]" labels="false" cell="9" title="Dense block" /> </span> ``` The `unit` prop renames the age columns in the summary and announcements — `"month"`, `"week"`, `"day"`, whatever the cohort period is. ## Edge cases [#edge-cases] ```tsx `"> <CohortTriangle data="[{ label: "Jan", values: [1, 0.6, 0.45, 0.4] }]" unit="month" cell="16" title="One cohort" /> ``` ```tsx `" > <CohortTriangle data="[{ label: "Jan", values: [1, 0.6, null, 0.4] }]" cell="16" title="Gap slot" /> ``` ```tsx `" > <CohortTriangle data="[ { label: "Jan", values: [100, 62, 48] }, { label: "Feb", values: [100, 47] }, ]" cell="16" unit="month" title="Percent-scale input" /> ``` ```tsx `" > <CohortTriangle data="[ { label: "Jan", values: [1, 0.62, 0.48] }, { label: "Feb", values: [1, 0.47] }, ]" cell="16" unit="month" locale="de-DE" title="Localized retention" /> ``` A single cohort skips the comparison and just states its first reading. A `null` (or any non-finite) value renders as an outlined **gap** slot — a "measured nothing here" cell, never a shaded 0%. `data` accepts either a 0–1 fraction or a 0–100 percent series — whichever the max value implies — so a raw percent export renders identically to its fraction form. With a `locale`, every announced number follows that locale's own formatting. ## Why this default [#why-this-default] Rows are cohorts in input order and columns are age, because the decision — *which vintage retains worst* — is a **vertical** read at a fixed age, and the ragged right edge falls out naturally from newer cohorts simply having fewer observed ages. Intensity is quantized to five discrete levels (never a continuous ramp): a smooth gradient would imply a precision a handful of pixels cannot deliver. A worst-vintage flag is **off** by default — the marks stay honest and the summary names the laggard in words instead of painting a verdict onto the grid. ## Accessibility [#accessibility] Intensity is a color channel, so CohortTriangle always pairs it with a numeric summary that compares at equal maturity — **"5 cohorts; at month 1, Mar retains worst (47%); newest May starts at 100%."**. Direction is stated in words, never by color alone, so it survives forced-colors and color-blind viewing. The interactive entry adds 2-D arrow-key navigation, announcing each cell as *"Feb cohort, month 1: 58%"* as you move. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label, values }[]` | One row per cohort; values[i] = retention at age i (0–1 or 0–100, ragged). | | `labels` | `boolean` | Cohort labels in a left gutter (default true; drops at tiny cell sizes). | | `highlight` | `string` | Ring the cohort with this label — the comparison focus. | | `unit` | `string` | Age-column noun for the summary (default "period"). | | `cell` | `number` | Cell edge length in viewBox units. | | `title` | `string` | Accessible name; joins the auto summary. | | `summary` | `string \| false` | Override or disable the auto summary. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # CometTrail (/docs/charts/comet-trail) CometTrail answers "where is the value now, and where has it just been?" A bright head dot marks the current value; behind it, a trail of recent points fades out with age, like a comet. In the interactive entry the head eases to each new value and the old head decays into the trail, so a live stream draws a comet and a stall goes still. Opacity encodes **age only** — the y position does the value — so the trail is recency context, never data you have to decode. ```tsx <CometTrail data="[40, 45, 50, 55, 60, 65, 70, 72, 75, 78, 80, 84, 87]" title="Latency" width="90" /> ``` ## Install [#install] ```tsx import { CometTrail } from "@microcharts/react/comet-trail"; <CometTrail data={rollingWindow} title="Latency" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## Motion, and reduced motion [#motion-and-reduced-motion] Motion happens **only on a data change** — there is no idle loop. When a new value arrives the head eases (\~200 ms, the library's canonical strong ease-out) from its old position to the new one and the previous head steps down into the trail; a continuous stream produces the comet, a stalled stream simply goes still, which is itself the signal (staleness reads as stillness). The dot jumps to the truth, eased — it never simulates phantom positions between updates. Under `prefers-reduced-motion` the head repositions instantly (the static encoding is already complete), and the same is true off-screen — one shared viewport check means the ease only runs while the chart is actually in view. ## When to use it [#when-to-use-it] * **Good for** — a live price or metric with a little recency context, a realtime KPI that should show momentum, or per-stream "where is it now" in a table. * **Avoid for** — the full history (`Sparkline`), an exact multi-point comparison (`Sparkline`, `DotPlot`), or discrete events (`HeartbeatBlip`). ## Sizing [#sizing] `width` and `height` are viewBox units that also set the rendered pixel box — they default to `60 × 16`, sized to sit in a table cell or beside a line of text. Omit them and drive the width from CSS to fill a column; the viewBox keeps the aspect ratio. `trail` controls how many recent points the tail carries, which is a density decision rather than a size one. ## Variants [#variants] ```tsx <CometTrail data={window} label="none" />`" > <span className="inline-flex gap-6 items-center"> <CometTrail data="[40, 45, 50, 55, 60, 65, 70, 72, 75, 78, 80, 84, 87]" trail="6" width="100" summary="false" /> <CometTrail data="[40, 45, 50, 55, 60, 65, 70, 72, 75, 78, 80, 84, 87]" label="none" width="100" summary="false" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <CometTrail data="[]" title="No stream yet" width="90" /> ``` ```tsx `"> <CometTrail data="[52]" title="First reading" width="90" /> ``` ```tsx `" > <CometTrail data="[40, 55, 48, 62]" trail="20" title="Short stream" width="90" /> ``` Empty data draws just the frame, with "No data." as the summary. A single point has no trail to fade — just the head and "Now 52." A `trail` larger than the data never backfills or pads: the trail simply shows every point there is. ## Why this default [#why-this-default] `label="last"` is on because a live value without its number is a mood, not a measurement — the whole point is knowing where it is now. Opacity encodes age and nothing else, so changing `trail` gives you more or less recency context without ever changing the head read. The trail is capped at 20 points: past that it stops being a trail and becomes a sparkline, which is the better tool for the full history. ## Accessibility [#accessibility] The accessible name is the now-value and the recent trend — **"Now 62, rising over the last 3 updates."** — or just the value when there is a single point, as in the edge case above: **"Now 52."** Arrow keys step back through the trail ("3 updates ago: 78.") and return toward now; motion is gated on `prefers-reduced-motion`, and the trail opacity is age, never a value you must read from fading. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | The rolling window, oldest → newest (last = now). | | `trail` | `number` | Points kept visible (default 12, cap 20). | | `label` | `"last" \| "none"` | Numeral after the head (default last). | 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](/docs/quickstart#the-shared-grammar). # ConfusionGrid (/docs/charts/confusion-grid) ConfusionGrid answers "where do the errors go?" — the one thing accuracy-as-a-number hides. Rows are the actual class, columns the predicted class, and each cell's ink is the row-normalized share: of the actual X, where did the predictions go? The diagonal (agreement) is accented by shape, never by colour, so good and bad are positions on the grid, not hues. The one-line key — rows actual, columns predicted — belongs next to every example. ```tsx `" > <ConfusionGrid data="{ labels: ["A", "B", "C"], counts: [[70, 8, 2], [6, 62, 12], [3, 9, 58]] }" label="accuracy" title="Classifier" size="120" /> ``` ## Install [#install] ```tsx import { ConfusionGrid } from "@microcharts/react/confusion-grid"; <ConfusionGrid data={counts} title="Classifier" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — classifier evaluation, and any paired-classification agreement (triage vs outcome, plan vs actual, rater A vs rater B). * **Avoid for** — a single accuracy number (Delta) or more than four classes (use a full-size heatmap). ## Variants [#variants] ```tsx `"> <ConfusionGrid data="{ labels: ["A", "B", "C"], counts: [ [70, 8, 2], [6, 40, 34], [3, 9, 58], ], }" accent="errors" title="Worst confusion" size="110" /> ``` ## Edge cases [#edge-cases] ```tsx 4 clamps to the first four classes (dev-warns)" code="`<ConfusionGrid data={{ labels: ["A", "B", "C", "D", "E"], counts: [ [40, 3, 1, 0, 2], [4, 38, 2, 1, 0], [1, 3, 44, 2, 1], [0, 2, 3, 36, 4], [2, 1, 0, 3, 41], ], }} title="5 classes" />`" > <ConfusionGrid data="{ labels: ["A", "B", "C", "D", "E"], counts: [ [40, 3, 1, 0, 2], [4, 38, 2, 1, 0], [1, 3, 44, 2, 1], [0, 2, 3, 36, 4], [2, 1, 0, 3, 41], ], }" title="5 classes" size="110" /> ``` A fifth class doesn't grow the grid — legibility caps at 4×4, so a `k` of 5 or more clamps to the first four labels and rows/columns, with a dev warning steering to a full-size heatmap. The grid never silently drops classes in production (the warning is dev-only), but the render itself does truncate; pass pre-filtered `labels`/`counts` if you need a specific four. ```tsx `" > <ConfusionGrid data="{ labels: ["cat", "dog"], counts: [ [40, 10], [0, 0], ], }" title="No dog samples" size="90" /> ``` ## Why this default [#why-this-default] The row view answers the question practitioners actually ask — "of the real cats, how many did we call dogs?" — so row-normalization is stated in the summary phrasing ("% of cats") and the denominator travels with every number. Accuracy is off by default and never rendered without the grid: the number may not leave its context. The diagonal accent is a shape (an inset stroke), and the ink ramp is identical for agreement and error cells — good and bad are positions, not colours, which is what keeps it readable under forced colours. ## Accessibility [#accessibility] The accessible name states accuracy and the worst confusion, with the row-normalized denominator carried in the phrasing — the grid at the top of this page reads **"Accuracy 73%. Most confused: B predicted as C (43% of Bs)."** A perfect classifier reads **"Accuracy 100%. No confusion."**, and a class with no samples is named rather than hidden — the `cat`/`dog` example above reads **"Accuracy 80%. Most confused: cat predicted as dog (20% of cats). No dog samples."** The interactive entry roves the cells with the arrow keys (Home and End jump to the two ends of the diagonal), announcing each cell's actual and predicted class as a share of the actual class. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ labels, counts }` | k×k matrix; rows actual, columns predicted. | | `normalize` | `"row" \| "none"` | Row = recall view (default). | | `accent` | `"diagonal" \| "errors"` | Agreement or the worst confusion. | | `label` | `"accuracy" \| "none"` | Overall accuracy in the gutter (opt-in). | | `shape` | `"square" \| "round"` | Cell shape from the shared vocabulary (default 'square'). | | `color` | `string` | Accent fill override. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Constellation (/docs/charts/constellation) Constellation answers "when did the rare events happen, and how big were they?" Each event is a dot placed by time (x) and value (y), with an optional magnitude driving its area-true size. A hairline line connects the events in time order, so the sequence of a handful of incidents reads at a glance. It is built for *rare* events — a dozen or fewer; dense streams belong to `Seismogram` or `EventTimeline`. ```tsx ["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep"][x]; <Constellation data={[ { x: 0, y: 40, m: 2 }, { x: 2, y: 90, m: 7 }, { x: 5, y: 30, m: 3 }, { x: 8, y: 65, m: 5 }, ]} xFormat={month} title="Incidents" />`" > <Constellation data="[{ x: 0, y: 40, m: 2 }, { x: 2, y: 90, m: 7 }, { x: 5, y: 30, m: 3 }, { x: 8, y: 65, m: 5 }]" xFormat="(x) => ["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep"][x]" title="Incidents" width="120" height="34" /> ``` ## Install [#install] ```tsx import { Constellation } from "@microcharts/react/constellation"; <Constellation data={[ { x: 0, y: 40, m: 2 }, { x: 2, y: 90, m: 7 }, { x: 5, y: 30, m: 3 }, { x: 8, y: 65, m: 5 }, ]} title="Incidents" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — sparse incidents or outages on a timeline, milestones carrying a magnitude, or any rare events where the sequence is the story. * **Avoid for** — dense event streams (`Seismogram`, `EventTimeline`), a continuous trend (`Sparkline`), or precise value comparison (dot area is a low-precision channel). ## Variants [#variants] ```tsx <Constellation data={events} connect={false} />`" > <span className="inline-flex gap-6 items-center"> <Constellation data="[ { x: 0, y: 40, m: 2 }, { x: 2, y: 90, m: 7 }, { x: 5, y: 30, m: 3 }, { x: 8, y: 65, m: 5 }, ]" label="max" width="110" height="32" summary="false" /> <Constellation data="[ { x: 0, y: 40, m: 2 }, { x: 2, y: 90, m: 7 }, { x: 5, y: 30, m: 3 }, { x: 8, y: 65, m: 5 }, ]" connect="false" width="110" height="32" summary="false" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <Constellation data="[]" title="No incidents" width="110" height="28" /> ``` ```tsx `"> <Constellation data="[{ x: 3, y: 40 }]" title="One incident" width="110" height="28" /> ``` ```tsx `"> <Constellation data="[{ x: 0 }, { x: 2 }, { x: 5 }, { x: 8 }]" title="No values" width="110" height="28" /> ``` Empty data draws no marks at all — just the sized box — with "No data." as the summary. A single event has no line to draw — just one dot, and the summary says "1 event at …" rather than forcing a range. When every point omits `y`, the vertical spread is deterministic jitter for legibility only — the summary and the interactive readout never mention it, and the connector's slope carries no meaning in that mode. ## Why this default [#why-this-default] The chronology line is on by default because the sequence is usually the story of rare events — you want to see the order and rhythm, not just a scatter. Dot size is *area-true* (`r ∝ √m`), because area is how the eye reads magnitude; it is a deliberately low-precision channel, so the number lives in the summary and the hover readout, not in a size you are asked to measure. When no event carries a value, the vertical position is **deterministic jitter that encodes nothing** — it only spreads the dots so they do not stack. In that case the connector's slope is meaningless (it still runs in time order), and the summary never mentions vertical position. Time is sacred: the x position is never jittered, so simultaneous events sit at the same x. ## Accessibility [#accessibility] The accessible name states the count, the span, and the largest event — **"4 events between 0 and 8; largest at 8."** The interactive entry lets you arrow through the events chronologically, each announced with its time, value, and magnitude through a polite live region; a hover readout shows the same. Magnitude is redundant with the dot size, never carried by it alone. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ x: number; y?: number; m?: number }[]` | Events: x = time, y = value, m = magnitude (area-true size). | | `connect` | `boolean` | The faint chronology line (default true). | | `label` | `"max" \| "none"` | Numeral at the largest event. | | `xFormat` | `(x: number) => string` | Formats time for the summary (e.g. a month name). | | `xDomain` | `[number, number]` | Time (x) extent (default: data extent). | | `rBase` | `number` | Base dot radius in viewBox units (default 1.6). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # ControlStrip (/docs/charts/control-strip) ControlStrip answers "is the process in control — or did something leave the band?". It's a Shewhart individuals chart: the control band is the process center ± 3σ̂, where **σ̂ = mean moving range ÷ 1.128** — the individuals estimator, stated outright (sample SD is not used; it inflates the limits under drift). In-control points are bare vertices; only out-of-control points are marked (ringed, in the negative color), because an in-control process should look boring. ```tsx `" > <ControlStrip data="[74, 73, 75, 74, 76, 73, 74, 75, 74, 73, 82, 74, 75, 73, 74, 76, 74, 73, 75, 74, 66, 74, 75, 74, 73, 76, 74, 75, 74, 73]" title="Line 3 fill weight" width="260" height="26" /> ``` ## Install [#install] ```tsx import { ControlStrip } from "@microcharts/react/control-strip"; <ControlStrip data={weights} title="Line 3 fill weight" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a production line or metric in a table cell, an SPC control chart in a KPI card, flagging out-of-control excursions at a glance. * **Avoid for** — a plain trend (Sparkline) or a strongly trending series (ChangePoint — control limits assume a stationary process). ## Variants [#variants] ```tsx <ControlStrip data={weights} dots="all" />`" > <span className="inline-flex flex-col gap-1.5"> <ControlStrip data="[ 74, 73, 75, 74, 76, 73, 74, 75, 74, 73, 82, 74, 75, 73, 74, 76, 74, 73, 75, 74, 66, 74, 75, 74, 73, 76, 74, 75, 74, 73, ]" rules="we" title="WE rules" width="220" height="24" /> <ControlStrip data="[74, 73, 75, 74, 76, 73, 74, 75, 74, 73, 82, 74, 75, 73, 74, 76]" dots="all" title="All dots" width="220" height="24" /> </span> ``` ```tsx `" > <ControlStrip data="[2.4, 2.5, 2.45, 2.55, 2.5, 2.6, 2.4, 2.5, 2.45, 2.9, 2.5, 2.55]" format="{ maximumFractionDigits: 1 }" locale="de-DE" title="Localized limits" width="220" height="24" /> ``` The chart draws no in-chart numbers, so `format`/`locale` shape the accessible summary and the interactive announcements — the strip above reads "All 12 points within control limits (center 2,5, limits 2,1–2,9)." with German decimal commas. ## Edge cases [#edge-cases] ```tsx `" > <ControlStrip data="[10, 11, 9, 10, 12, 8]" title="Provisional" width="160" height="22" /> ``` ```tsx `" > <ControlStrip data="[5, 5, 5, 5]" title="Constant" width="160" height="22" /> ``` ## Why this default [#why-this-default] Flag only the out-of-band points, because an in-control process should look boring — the eye should land on the exception, not scan every dot. The σ̂ estimator is the moving-range one (`MR̄ / 1.128`), never a vague "±3 sigma"; `limits="percentile"` states its exact quantiles for skewed processes. Western Electric rules are conventions, so the implemented subset is enumerated (WE-1 beyond 3σ, WE-2 two-of-three beyond 2σ, WE-4 eight on one side) and none fires silently. With fewer than 10 points the band is dashed and the summary says "limits provisional". ## Accessibility [#accessibility] The accessible name states the excursion count, the center, and the limits — **"2 of 30 points outside control limits (center 74.17, limits 67.84–80.49)."**; an in-control run reads "All N points within control limits …". The interactive entry steps the points and out-of-control points announce which limit they crossed. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Sequential measurements. | | `limits` | `"sigma" \| "percentile"` | ±3σ̂ (default) or empirical p0.135/p99.865 for skewed processes. | | `baseline` | `number` | Known process center from a reference period (else = mean). | | `rules` | `"none" \| "we"` | Western Electric secondary run rules (WE-1/2/4 subset). | | `dots` | `"out" \| "all" \| "none"` | Mark only out-of-control points (default), every point, or none. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # CoverageStrip (/docs/charts/coverage-strip) CoverageStrip answers "can I trust this data — where was nothing measured?". Measured slots are filled; gaps are hollow with a hairline outline. The distinction between `null` (no measurement) and `0` (a measured zero) is the whole chart, and it is carried by **shape**, so it survives forced-colors and print. Nothing is ever interpolated across a gap. ```tsx <CoverageStrip data="[3, 4, null, 5, 0, null, null, 6, 8, 7, null, 9, 11, 10]" expected="18" label="percent" title="Sensor uptime" width="240" height="16" /> ``` ## Install [#install] ```tsx import { CoverageStrip } from "@microcharts/react/coverage-strip"; <CoverageStrip data={readings} expected={18} label="percent" title="Sensor uptime" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — data-quality cells beside a metric, sensor-uptime rows, trailing-gap detection. * **Avoid for** — magnitude over time (HeatStrip) or exact values (Sparkline). ## Variants [#variants] ```tsx <CoverageStrip data={readings} shape="round" />`" > <span className="inline-flex flex-col gap-1.5"> <CoverageStrip data="[3, 4, null, 5, 0, null, 6, 8, 7, null, 9, 11]" mode="intensity" domain="[0, 12]" title="Intensity" width="200" height="12" /> <CoverageStrip data="[3, 4, null, 5, 0, null, 6, 8, 7, null, 9, 11]" shape="round" title="Round" width="200" height="12" /> </span> ``` ```tsx `" > <CoverageStrip data="[3, 4, null, 5, 0, null, null, 6, 8, 7, null, 9, 11, 10]" expected="18" label="percent" locale="de-DE" title="Localized coverage" width="200" height="14" /> ``` `locale` formats the coverage percentage in the gutter and the accessible summary — the strip above reads "56 %" (German percent spacing) instead of "56%". `format` shapes the measured values the interactive entry announces. ## Edge cases [#edge-cases] ```tsx `" > <CoverageStrip data="[1, 1, 1]" expected="8" label="percent" title="Trailing gap" width="180" height="16" /> ``` ```tsx `"> <CoverageStrip data="[3, 0, null, 5]" title="Zero vs missing" width="100" height="16" /> ``` ```tsx `"> <CoverageStrip data="[]" title="Empty" width="80" height="16" /> ``` ## Why this default [#why-this-default] Shape carries the presence/absence distinction, not just color, so it survives forced-colors and print. A measured `0` is a filled cell like any other value; only `null` (no record) is hollow — the two never look the same. `expected` lets a trailing shortfall count as coverage loss: a feed that simply stops reporting is the worst gap of all, so it isn't silently dropped from the denominator. Nothing is ever interpolated across a gap — a missing slot stays visibly empty rather than being smoothed into its neighbors. ## Accessibility [#accessibility] The accessible name states how many slots were measured, the coverage percentage, and the longest gap — **"10 of 18 slots measured (56 %); longest gap 4 slots."** An empty series states "No data." instead. The interactive entry roves slots with ←/→, announcing each one as a measured value or "no measurement". The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | Time-ordered slots; null = no measurement, 0 = a measured zero. | | `expected` | `number` | Slots the window should contain — lets trailing missingness count. | | `mode` | `"binary" \| "intensity"` | Presence only (default), or shade measured cells by value. | | `steps` | `number` | Intensity granularity (default 5). | | `shape` | `"square" \| "round" \| "dot"` | Cell shape from the shared vocabulary (default 'square'). | | `label` | `"percent" \| "none"` | State the coverage number in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # CyclePlot (/docs/charts/cycle-plot) CyclePlot answers "what repeats beneath the trend — and is any slot itself drifting?". The series is reshaped into `period` slots (7 for weekdays, 12 for months); each slot shows its own raw values across cycles as a muted polyline in **time order**, plus a mean tick, and the accent spine connects the slot means. Seasonality (the spine) and drift (the within-slot lines) are different questions of the same data — so they never share a mark. ```tsx `" > <CyclePlot data="[38, 40, 45, 48, 52, 61, 44, 38, 42, 45, 48, 52, 61, 44, 38, 44, 45, 48, 52, 61, 44, 38, 46, 45, 48, 52, 61, 44, 38, 48, 45, 48, 52, 61, 44, 38, 50, 45, 48, 52, 61, 44]" period="7" slots="["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]" cycleUnit="weeks" title="Weekly shape" width="200" height="40" /> ``` ## Install [#install] ```tsx import { CyclePlot } from "@microcharts/react/cycle-plot"; <CyclePlot data={daily} period={7} slots={weekdays} cycleUnit="weeks" title="Weekly shape" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a KPI card that says "the week has a shape", weekday traffic / hourly load / monthly sales seasonality, or spotting one slot that is itself drifting. * **Avoid for** — a plain time series (Sparkline) or one composition (SegmentedBar). `period` outside 4–12 warns in development: below that there is no cycle to see, above it the slots stop being separable. ## Variants [#variants] ```tsx <CyclePlot data={[38, 40, 45, 48, 52, 61, 44, 38, 42, 45, 48, 52, 61, 44, 38, 44, 45, 48, 52, 61, 44]} period={7} trend={false} />`" > <span className="inline-flex gap-4 items-center"> <CyclePlot data="[38, 40, 45, 48, 52, 61, 44, 38, 42, 45, 48, 52, 61, 44, 38, 44, 45, 48, 52, 61, 44]" period="7" center="median" width="150" height="32" /> <CyclePlot data="[38, 40, 45, 48, 52, 61, 44, 38, 42, 45, 48, 52, 61, 44, 38, 44, 45, 48, 52, 61, 44]" period="7" trend="false" width="150" height="32" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <CyclePlot data="[null, 40, 45, 48, 52, 61, null, 42, 45, 48, 52, 61, null, 44, 45, 48, 52, 61]" period="6" title="One slot always missing" width="160" height="32" /> ``` ```tsx `" > <CyclePlot data="[38, 45, 52, 44, 40, 48, 61]" period="7" title="One cycle" width="160" height="32" /> ``` ```tsx `" > <CyclePlot data="[3800, 4000, 4500, 4800, 5200, 6100, 4400, 3800, 4200, 4500, 4800, 5200, 6100, 4400]" period="7" locale="de-DE" title="Localized visits" width="200" height="36" /> ``` A slot with no finite values in it draws no mean tick and no within-slot line; the spine connects the non-empty slots only, joining an empty slot's neighbours directly rather than dipping to a made-up center. A single cycle (one value per slot) draws the spine and dots as usual, but no within-slot polylines — a line needs at least two observations in a slot. ## Why this default [#why-this-default] A mean spine plus raw slot lines, because seasonality and drift are different questions asked of the same data — and answering both on one mark would blur them. The within-slot lines are never smoothed and never joined across a slot boundary: each slot's polyline begins and ends inside its own column, so a Monday trend can never bleed into Tuesday. The `center` choice is explicit — mean by default, median when a slot's distribution is skewed — and the interactive per-slot announcement names which one it used. ## Accessibility [#accessibility] The accessible name states the peak and dip slots and any leading drift — **"Peaks slot 6 (61), dips slot 1 (38); slot 2 rising across 3 cycles."** The interactive entry steps the slots (mean, cycle count, drift) with ←/→, and steps the individual observations within a slot with ↑/↓. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | A flat series, reshaped row-major into `period` slots. | | `period` (required) | `number` | Slots per cycle (4–12) — e.g. 7 for weekdays. | | `slots` | `string[]` | Slot names for summaries, e.g. weekday labels. | | `center` | `"mean" \| "median"` | Center statistic — median for skewed slot distributions. | | `trend` | `boolean` | Within-slot micro-trend line (default true); false = spine + ticks only. | | `spine` | `boolean` | The slot-center spine (default true); false leaves within-slot drift only. | | `cycleUnit` | `string` | Cycle noun for the summary, e.g. 'weeks' (default 'cycles'). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # DataDiff (/docs/charts/data-diff) DataDiff answers "what changed between these two versions?". Each key gets a diverging bar: **removed leftward, added rightward, both always drawn** on one symmetric shared scale. Net is a mark you can turn on, never a replacement for the two bars — a +500/−480 churn and a +20/−0 trickle must never look alike. ```tsx <DataDiff data="[ { key: "users", added: 340, removed: 120 }, { key: "orders", added: 88, removed: 30 }, { key: "items", added: 40, removed: 20 }, { key: "tags", added: 24, removed: 8 }, { key: "notes", added: 12, removed: 6 }, { key: "flags", added: 8, removed: 3 }, ]" title="Schema diff" width="200" height="72" /> ``` ## Install [#install] ```tsx import { DataDiff } from "@microcharts/react/data-diff"; <DataDiff data={diff} title="Schema diff" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a table cell per dataset version, a KPI card for a sync or import job, any per-key added/removed audit where churn matters. * **Avoid for** — a plain ranking (MiniBar) or parts of a single whole (SegmentedBar). ## Variants [#variants] ```tsx <DataDiff data={[ { key: "users", added: 340, removed: 120 }, { key: "orders", added: 88, removed: 30 }, { key: "items", added: 40, removed: 20 }, ]} net label="totals" />`" > <span className="inline-flex gap-4"> <DataDiff data="[ { key: "users", added: 340, removed: 120 }, { key: "orders", added: 88, removed: 30 }, { key: "items", added: 40, removed: 20 }, ]" width="150" height="56" /> <DataDiff data="[ { key: "users", added: 340, removed: 120 }, { key: "orders", added: 88, removed: 30 }, { key: "items", added: 40, removed: 20 }, ]" label="totals" width="150" height="56" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <DataDiff data="[]" title="No keys" width="100" height="24" /> ``` ```tsx `"> <DataDiff data="[ { key: "a", added: 0, removed: 0 }, { key: "b", added: 0, removed: 0 }, ]" title="No changes" width="100" height="24" /> ``` An empty `data` array renders an empty chart and reports **"No data."** A non-empty diff where every key is 0/0 still draws its hairline placeholder ticks and reports **"No changes across 2 keys."** — the keys are named even when nothing about them changed. ## Why this default [#why-this-default] Both directions are always drawn, because net-only diffs hide churn: a table that added 500 rows and dropped 480 is not the same event as one that added 20 and dropped nothing, even though both net to roughly the same number. One symmetric scale spans every row so a big change never shrinks to fit a small one, and a key with no change still gets a hairline tick — the absence of a change is not the absence of the key. Cross-chart comparison goes through a shared `domain`. ## Accessibility [#accessibility] The accessible name states the totals, the key count, and the single largest change — **"+468 added, −170 removed across 3 keys; largest change: users (+220)."** The interactive entry steps the rows and announces each key's added, removed, and net change. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ key; added; removed }[]` | Per-key change counts — added and removed are non-negative magnitudes. | | `labels` | `boolean` | In-chart key tags for standalone use (host tables carry keys by default). | | `net` | `boolean` | A tick at added−removed per row — a summary mark, never the two bars. | | `order` | `"data" \| "net" \| "magnitude"` | Default 'data' keeps input order (schema order is often meaningful). | | `label` | `"totals" \| "none"` | 'totals' prints a +added / −removed footer. | | `maxItems` | `number` | Row cap (default 12); rows beyond it are dropped with a dev warning. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Delta (/docs/charts/delta) Delta is a text-first metric: a signed number with a direction glyph. It reads inline, next to a KPI, or inside a table cell. Direction is always doubled — a triangle *and* a color — so it never relies on color alone. ```tsx <span className="text-lg"> <Delta value="0.124" title="Revenue vs last week" /> </span> ``` ## Install [#install] ```tsx import { Delta } from "@microcharts/react/delta"; <Delta value={0.124} title="Revenue vs last week" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a KPI's change, period-over-period percent, inline metric movement. * **Avoid for** — showing a series or comparing magnitudes across items. ## Sizing [#sizing] Delta is text, not a fixed box — it takes the `font-size` of whatever wraps it and its glyph scales in `em`. Size it by the surrounding type: inline, it inherits the sentence; beside a KPI figure, lift the font-size to match. ## Variants [#variants] `from` derives a percent change; `positive="down"` flips only the color for metrics where down is good (latency, churn, cost). ```tsx `"> <span className="text-lg"> <Delta value="0.124" title="Percent" /> </span> ``` ```tsx `"> <span className="text-lg"> <Delta value="128" from="100" title="From prior" /> </span> ``` ```tsx `"> <span className="text-lg"> <Delta value="-0.08" title="Down is bad" /> </span> ``` ```tsx `"> <span className="text-lg"> <Delta value="-0.05" positive="down" title="Down is good" /> </span> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, the magnitude follows that locale's own grouping and decimal marks (a German reader sees a comma decimal and a space before the `%`, not a period). The leading sign is the library's own `+` / `−`, so it reads the same in every locale. ```tsx `"> <span className="text-lg"> <Delta value="0.124" format="{ style: "percent", maximumFractionDigits: 1 }" locale="de-DE" title="Localized change" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <span className="text-lg"> <Delta value="0" title="Flat" /> </span> ``` ```tsx <Delta value={Infinity} />`" > <span className="inline-flex gap-4 text-lg"> <Delta value="Number.NaN" title="Not a number" /> <Delta value="Number.POSITIVE_INFINITY" title="Infinite" /> </span> ``` A zero delta shows the flat glyph and **"No change."** — never a `+0%`/`−0%` that implies a direction with nothing behind it. `NaN` and `±Infinity` degrade the same way: the flat glyph, an em dash instead of a number, and **"No change."** rather than a misleading `NaN%`. ## Why this default [#why-this-default] Direction is always double-encoded — the triangle's shape carries it as much as the color does — because a red/green-only read fails for color-blind viewers and under `forced-colors`. `positive` flips only which color means "good"; it never changes which way the glyph points, so a metric where down is good (latency, churn, cost) still shows an honest down-pointing triangle, just in the "good" color. Percent is the default format because most deltas are relative change, not raw magnitude — pass `format` for currency, counts, or any other unit. Non-finite input renders as an em dash rather than `NaN%`, because a broken number should read as "nothing to report," not as a fabricated value. ## Accessibility [#accessibility] Delta renders accessible inline text — the glyph is decorative and the value carries the meaning. Color is a redundant channel on top of the direction glyph and the sign, so the change survives forced-colors and color-blind viewing. The interactive entry re-announces the figure through a polite live region when the value changes. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The change, or current value when from is set. | | `from` | `number` | Prior value; Delta shows the percent change. | | `positive` | `"up" \| "down"` | Which direction is good (colors only). | | `format` | `Intl.NumberFormatOptions \| fn` | Number formatting. | | `locale` | `string \| string[]` | BCP 47 locale(s) for the formatted number. | | `summary` | `string \| false` | Override or disable the auto summary. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # DepthWedge (/docs/charts/depth-wedge) DepthWedge answers "how much pressure is stacked on each side of the current level, and how wide is the gap between them?". Demand accumulates leftward from the spread and supply rightward, so the two filled wedges show the book's posture in a glyph. The y-scale is linear, full stop — log-depth reading belongs to full-size tools. ```tsx `" > <DepthWedge data="{ demand: [ { level: 99.75, amount: 420 }, { level: 99.5, amount: 360 }, { level: 99.25, amount: 280 }, { level: 99, amount: 200 }, { level: 98.5, amount: 120 }, ], supply: [ { level: 100.25, amount: 300 }, { level: 100.5, amount: 240 }, { level: 100.75, amount: 160 }, { level: 101, amount: 90 }, ], }" title="Order book" width="300" height="30" /> ``` ## Install [#install] ```tsx import { DepthWedge } from "@microcharts/react/depth-wedge"; <DepthWedge data={{ demand, supply }} title="Order book" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — order-book depth / liquidity, supply vs demand posture. * **Avoid for** — a time series (Sparkline) or a single ratio (Delta). ## Variants [#variants] ```tsx `" > <DepthWedge data="{ demand: [ { level: 99.5, amount: 420 }, { level: 99, amount: 260 }, ], supply: [ { level: 100.5, amount: 300 }, { level: 101, amount: 180 }, ], }" title="Normalized" width="300" height="30" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <DepthWedge data="{ demand: [ { level: 99.5, amount: 200 }, { level: 99, amount: 100 }, ], supply: [ { level: 100.5, amount: 200 }, { level: 101, amount: 100 }, ], }" title="Balanced" width="300" height="30" /> ``` ```tsx `" > <DepthWedge data="{ demand: [{ level: 99.5, amount: 200 }], supply: [] }" title="One-sided" width="300" height="30" /> ``` ## Why this default [#why-this-default] Linear scale plus a stated `levels` span because a wedge you can't interrogate must not editorialize — a silent log axis would exaggerate near-spread depth and flatter thin books. The visible range is part of the claim, so whenever the summary names a leading side it scopes the ratio with "within the shown range", and the spread — the gap between the best bid and best ask — is the headline number above the mid line. ## Accessibility [#accessibility] The accessible name states the posture, range-scoped — **"Demand outweighs supply 1.42× within the shown range; spread 1."** (the hero demo's order book). The interactive entry walks the levels with ←/→, announcing the cumulative depth on each side and its distance from the mid. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ demand, supply }` | Level/amount rows per side. | | `levels` | `number` | ± level distance from mid to include. | | `normalize` | `boolean` | Plot cumulative shares per side. | | `label` | `"spread" \| "none"` | The gap is the headline number. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # DicePips (/docs/charts/dice-pips) DicePips answers "what is this small count or severity?" the way dice do — a face you read without counting. The brain subitizes the canonical 1–6 patterns instantly. Zero is an empty face (zero, not missing); above six there is no subitizable pattern, so the face shows the exact numeral rather than inventing a seven-pip layout. The face never pretends. ```tsx <span className="inline-flex gap-3 items-center"> <DicePips value="1" size="20" title="one" /> <DicePips value="2" size="20" title="two" /> <DicePips value="3" size="20" title="three" /> <DicePips value="4" size="20" title="four" /> <DicePips value="5" size="20" title="five" /> <DicePips value="6" size="20" title="six" /> </span> ``` ## Install [#install] ```tsx import { DicePips } from "@microcharts/react/dice-pips"; <DicePips value={4} title="Severity" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a severity or rating 0–6 in a cell, an at-a-glance small count in a sentence, or an incident-severity badge. * **Avoid for** — counts above six (TallyMarks), magnitudes (MiniBar), or proportions (Progress). ## Variants [#variants] ```tsx <DicePips value={9} />`" > <span className="inline-flex gap-4 items-center"> <DicePips value="5" face="false" size="22" /> <DicePips value="9" size="22" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <DicePips value="0" size="22" /> ``` ```tsx `"> <DicePips value="-2" size="22" /> ``` ```tsx `"> <DicePips value="3.6" size="22" /> ``` ## Why this default [#why-this-default] The face outline keeps a lone die legible on any surface, so it is on by default; `face={false}` drops it for repeated table columns where the header already frames the column. Six is the ceiling because pip patterns above six are not subitizable — asking the reader to count invented pips would be slower than reading a number, so the chart refuses and shows the numeral instead. That numeral fallback is the documented honesty rule, shown live at `value={9}`. ## Accessibility [#accessibility] The accessible name states the value against its range — **"4 out of 6."** — and drops the frame to just the exact number once past six (**"9."**). Zero reads "0 out of 6." (a real zero), and an invalid value reads "No data." The interactive entry pops the pips into place on change (a short scale-up with a per-pip stagger, skipped under `prefers-reduced-motion`) and announces the new face through a polite live region; the pips are one value, so there is no cursor to move. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | Integer 0–6 (rounded); above 6 shows a numeral. | | `face` | `boolean` | Draw the die outline (default true). | 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](/docs/quickstart#the-shared-grammar). # DotPlot (/docs/charts/dot-plot) DotPlot answers "how do a few named values compare on one scale?" with the minimum ink per comparison. Dots over bars when the scale doesn't start at zero — position lies less than truncated bar length. ```tsx `" > <DotPlot data="[ { label: "Ada", value: 96 }, { label: "Kim", value: 41 }, { label: "Sam", value: 88 }, ]" title="Review scores" width="180" height="66" /> ``` ## Install [#install] ```tsx import { DotPlot } from "@microcharts/react/dot-plot"; <DotPlot data={team} title="Review scores" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — KPI leaderboards, named comparisons in cards, rows where a truncated bar would lie. * **Avoid for** — more than 7 rows or time series (Sparkline). ## Variants [#variants] ```tsx `" > <DotPlot data="[ { label: "Ada", value: 96 }, { label: "Kim", value: 41 }, { label: "Sam", value: 88 }, ]" title="Magnitude read" width="180" height="66" /> ``` ```tsx `"> <DotPlot data="[ { label: "Ada", value: 96 }, { label: "Kim", value: 41 }, { label: "Sam", value: 88 }, ]" label="value" highlight="Ada" title="Leaderboard" width="180" height="66" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <DotPlot data="[]" title="No data" width="100" height="16" /> ``` ```tsx `"> <DotPlot data="[{ label: "Only", value: 42 }]" title="Single" width="100" height="16" /> ``` ```tsx `" > <DotPlot data="[ { label: "Ada", value: 96 }, { label: "Kim", value: null }, { label: "Sam", value: 88 }, ]" title="Gap preserved" width="180" height="66" /> ``` An empty series has nothing to compare, so no dots draw and the accessible name reads **"No data."** A single category still renders normally — one dot, one label — with the summary's "category"/"categories" wording matching the count (**"1 category. Highest Only 42, lowest Only 42."**). A `null` value draws no dot and no label for its row, but the row still occupies its slot in the vertical rhythm — the real values around it keep the same spacing they'd have in a fully populated set — and it's excluded from the category count in the summary, not counted as a comparison with nothing. ## Why this default [#why-this-default] Without `stem` the domain fits the data (a position read); with `stem` the domain is forced through zero (a magnitude read) — the prop flips the honesty regime, and the docs say so. Coincident dots on adjacent rows de-overlap by half a unit; labels truncate by character count and drop entirely when rows get too dense — all pure arithmetic, nothing measured. ## Accessibility [#accessibility] The accessible name carries count and extremes — **"3 categories. Highest Ada 96, lowest Kim 41."** The interactive entry roves rows and announces each with its rank (**"Ada: 96 — 1st of 3."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value }[]` | Named values. | | `stem` | `boolean` | Hairline from zero — flips to a magnitude read (zero-anchored domain forced). | | `highlight` | `number \| string` | Accent one category. | | `label` | `"value" \| "none"` | Value text beside each dot (drops out under 8-unit rows). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # DualSparkline (/docs/charts/dual-sparkline) DualSparkline answers "how is this series doing against its benchmark?" Exactly two series, ever — three overlapped lines at 16 px are unreadable (SparkGroup for that). The benchmark whispers: dashed, thinner, neutral — never distinguished by color alone. ```tsx <DualSparkline data="[12, 13, 12.4, 14, 15.2, 14.8, 16, 17.5, 17, 18.4, 19, 21]" compare="[12, 12.4, 12.8, 13.1, 13.6, 14, 14.2, 14.8, 15, 15.4, 15.8, 16]" title="Conversion vs market" width="220" height="28" /> ``` ## Install [#install] ```tsx import { DualSparkline } from "@microcharts/react/dual-sparkline"; <DualSparkline data={ours} compare={market} title="Conversion vs market" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — metric-vs-benchmark in table cells, actual-vs-plan in KPI cards. * **Avoid for** — 3+ series (SparkGroup), or different units per series (never dual axes). ## Variants [#variants] ```tsx <DualSparkline data={ours} compare={market} band={[13, 16]} />`" > <span className="inline-flex flex-col gap-3"> <DualSparkline data="[12, 13, 12.4, 14, 15.2, 14.8, 16, 17.5, 17, 18.4, 19, 21]" compare="[12, 12.4, 12.8, 13.1, 13.6, 14, 14.2, 14.8, 15, 15.4, 15.8, 16]" label="last" title="With last value" width="220" height="28" /> <DualSparkline data="[12, 13, 12.4, 14, 15.2, 14.8, 16, 17.5, 17, 18.4, 19, 21]" compare="[12, 12.4, 12.8, 13.1, 13.6, 14, 14.2, 14.8, 15, 15.4, 15.8, 16]" band="[13, 16]" title="With band" width="220" height="28" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <DualSparkline data="[12, 13, 12.4, 14, 15.2, 14.8, 16, 17.5]" compare="[12, 12.4, 12.8, 13.1]" title="Benchmark ends early" width="200" height="28" /> ``` ```tsx `"> <DualSparkline data="[12, null, 12.4, 14, null, 14.8, 16]" compare="[12, 12.4, null, 13.1, 13.6, null, 14.2]" title="Independent gaps" width="200" height="28" /> ``` ```tsx `" > <DualSparkline data="[1200, 1300, 1240, 1400, 1520, 1480, 1600]" compare="[1200, 1240, 1280, 1310, 1360, 1400, 1420]" label="last" locale="de-DE" title="Localized values" width="220" height="28" /> ``` Each series carries its own gaps independently — a `null` in `data` breaks only the primary line at that index, a `null` in `compare` only the benchmark, and the nearest-x hover still reports both values (or "no data" for whichever side is missing). With a `locale`, the endpoint label and both hover values follow that locale's grouping. ## Why this default [#why-this-default] One shared domain across both series — the entire point is comparability, so there are no dual axes and no per-series normalization. A shorter benchmark simply ends; stretching it would fake correlation. Coincident endpoints dedupe to one dot so ink never doubles. ## Accessibility [#accessibility] The accessible name reads both trends and both endpoints — **"Trending up 75% vs benchmark up 33%. Last 21 vs 16."** Identical series read "Matching benchmark." The interactive entry announces pairs (**"Point 9 of 12: 17 vs 15."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | The series being judged. | | `compare` (required) | `(number \| null)[]` | The benchmark — dashed, thinner, neutral. | | `curve` | `"linear" \| "smooth" \| "step"` | Line shape (default 'linear'). | | `band` | `[number, number]` | Normal-range band behind both (shared grammar). | | `label` | `"last" \| "none"` | Endpoint value label for the primary series. | | `dots` | `"auto" \| "none"` | Endpoint dots on both lines (default "auto"). | | `seriesStrings` | `SeriesStrings` | i18n strings for the per-series trend clauses. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # DualWindowMeter (/docs/charts/dual-window-meter) DualWindowMeter answers "is the level compliant against its target both right now and on average — momentary spikes vs sustained drift?". From one raw series it computes two rolling means: a thin fast window that reacts instantly and a thick slow window that carries the sustained read, both against a target line. It is the general form of any noisy metric with a compliance target. ```tsx <DualWindowMeter data="Array.from({ length: 60 }, (_, i) => -22 + Math.sin(i / 3) * 4 + Math.sin(i / 11) * 2 - (i > 40 ? 2 : 0))" target="-23" title="Loudness" format="{ maximumFractionDigits: 1 }" width="300" height="28" /> ``` ## Install [#install] ```tsx import { DualWindowMeter } from "@microcharts/react/dual-window-meter"; <DualWindowMeter data={samples} target={-23} format={{ maximumFractionDigits: 1 }} title="Loudness" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — loudness / LUFS metering, latency SLO or CPU-headroom compliance. * **Avoid for** — a single series (Sparkline) or anything without a target to compare against. ## Variants [#variants] ```tsx -22 + Math.sin(i / 3) * 4 + Math.sin(i / 11) * 2, ); <DualWindowMeter data={samples} target={-23} band={[-25, -21]} />`" > <DualWindowMeter data="Array.from({ length: 60 }, (_, i) => -22 + Math.sin(i / 3) * 4 + Math.sin(i / 11) * 2)" target="-23" band="[-25, -21]" title="Corridor" width="300" height="28" /> ``` ```tsx -22 + Math.sin(i / 3) * 4 + Math.sin(i / 11) * 2, ); // both window sizes are part of the reading — state them, never hide them <DualWindowMeter data={samples} target={-23} windows={[5, 20]} />`" > <DualWindowMeter data="Array.from({ length: 60 }, (_, i) => -22 + Math.sin(i / 3) * 4 + Math.sin(i / 11) * 2)" target="-23" windows="[5, 20]" title="Custom windows" width="300" height="28" /> ``` ```tsx -22 + Math.sin(i / 3) * 4 + Math.sin(i / 11) * 2 - (i > 40 ? 2 : 0), ); <DualWindowMeter data={samples} target={-23} format={{ maximumFractionDigits: 1 }} locale="de-DE" />`" > <DualWindowMeter data="Array.from({ length: 60 }, (_, i) => -22 + Math.sin(i / 3) * 4 + Math.sin(i / 11) * 2 - (i > 40 ? 2 : 0))" target="-23" format="{ maximumFractionDigits: 1 }" locale="de-DE" title="Localized readings" width="300" height="28" /> ``` With a `locale`, the right-edge readings and the accessible summary follow that locale's decimal mark — the fast reading above renders "-23,9", not "-23.9", and the accessible name reads "Slow window -25 vs target -23; fast -23,9." ## Edge cases [#edge-cases] ```tsx `" > <DualWindowMeter data="[48, 48.3, 48.6, 48.9, 49.2, 49.5, 49.8, 50.1, 50.4, 50.7]" target="50" title="Filling" width="200" height="28" /> ``` ## Why this default [#why-this-default] Thin-fast, thick-slow because the sustained read should carry more ink — a momentary spike on the fast trace matters less than a slow-window drift away from target. The window sizes are part of the reading, not a hidden implementation detail — `windows` is an explicit prop, and the examples that change it state both sizes. Both traces always share one domain; a trace begins only where its window has filled, never faking a partial-window value. ## Accessibility [#accessibility] The accessible name leads with the sustained read — **"Slow window -25 vs target -23; fast -23,9."** The interactive entry roves the samples with ←/→, announcing the fast value, the slow value, and the target at each point. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Raw samples; two rolling means are computed. | | `target` (required) | `number` | The compliance line — required. | | `windows` | `[number, number]` | Fast/slow integration windows (samples). | | `band` | `[number, number]` | A compliance corridor instead of one line. | | `domain` | `[number, number]` | Fix the vertical scale instead of auto-fitting both traces. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Dumbbell (/docs/charts/dumbbell) Dumbbell answers "where did each row start and end?". The hollow dot is *before*, the filled dot is *after* — direction is shape-coded, so it never relies on color alone. With `positive` the connector takes the valence token by direction. ```tsx <Dumbbell data="[{ from: 62000, to: 84000 }]" title="Band move" style="{ width: 200, height: 28 }" /> ``` ## Install [#install] ```tsx import { Dumbbell } from "@microcharts/react/dumbbell"; <Dumbbell data={[{ from: 62000, to: 84000 }]} title="Band move" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — salary bands, before/after per table row, ranges. * **Avoid for** — many categories where crossings matter (Slope) or the path between (Sparkline). ## Variants [#variants] ```tsx `" > <Dumbbell data="[ { label: "Paris", from: 52, to: 61 }, { label: "Oslo", from: 66, to: 60 }, ]" positive="up" title="Moves" style="{ width: 200, height: 44 }" /> ``` ```tsx `"> <Dumbbell data="[{ from: 40, to: 60 }]" label="value" domain="[0, 100]" title="With values" style="{ width: 240, height: 26 }" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <Dumbbell data="[{ from: 55, to: 55 }]" title="Flat" style="{ width: 200, height: 24 }" /> ``` When a row's `from` equals its `to`, the connector is dropped and only one filled dot is drawn — never a hollow-and-filled pair sitting on top of each other pretending to be two points. The summary says **"No change at 55."** for a single row. ## Why this default [#why-this-default] Hollow → filled reads as before → after without a legend, and renders identically whichever way the data runs — direction comes from the values, not the array order. For *ranges* (min→max, confidence spans) the docs require dropping `positive`: a range has no valence, and coloring it green or red would invent one. ## Accessibility [#accessibility] Single row: **"From 40 to 60, up 50%."**; a degenerate pair says **"No change at 55."**; multi-row leads with the largest change (**"2 rows. Largest change Paris, up 17%."**). The interactive entry roves rows with ↑/↓ (←/→ do the same), announcing each row's own pair — **"From 52 to 61, up 17%."** The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label?; from; to }[]` | Start/end pairs. | | `positive` | `"up" \| "down"` | Direction valence for CHANGES; drop it for ranges (no valence). | | `label` | `"value" \| "none"` | From/to values outside the dots (drop when the span is tight). | | `highlight` | `number \| string` | Accent one row. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # EnsembleGhosts (/docs/charts/ensemble-ghosts) EnsembleGhosts answers "what could happen, across the simulated futures?". It draws a faint bundle of member paths with one emphasized representative — because a mean line hides that futures disagree in **shape**, not just endpoint. Ghost selection is fully deterministic (evenly spaced endpoint-rank quantiles), so the same input renders identically every time. ```tsx `" > <EnsembleGhosts data="[[40, 41, 43, 45, 47, 50], [40, 39, 38, 36, 35, 33], [40, 42, 44, 47, 49, 52], [40, 40, 41, 41, 42, 43], [40, 43, 47, 52, 56, 61], [40, 38, 35, 32, 30, 28], [40, 41, 42, 44, 45, 46], [40, 39, 40, 41, 42, 44]]" title="Simulated futures" width="200" height="44" /> ``` ## Install [#install] ```tsx import { EnsembleGhosts } from "@microcharts/react/ensemble-ghosts"; <EnsembleGhosts data={futures} title="Simulated futures" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a KPI card that shows the futures, not the average; Monte-Carlo / simulation output where paths disagree in shape; showing that outcomes fan out. * **Avoid for** — interval precision (ForecastCone) or a single path (Sparkline). ## Variants [#variants] ```tsx <EnsembleGhosts data={[ [40, 41, 43, 45, 47, 50], [40, 39, 38, 36, 35, 33], [40, 42, 44, 47, 49, 52], [40, 43, 47, 52, 56, 61], [40, 38, 35, 32, 30, 28], ]} emphasis="median" />`" > <span className="inline-flex gap-4 items-center"> <EnsembleGhosts data="[ [40, 41, 43, 45, 47, 50], [40, 39, 38, 36, 35, 33], [40, 42, 44, 47, 49, 52], [40, 43, 47, 52, 56, 61], [40, 38, 35, 32, 30, 28], ]" width="150" height="40" /> <EnsembleGhosts data="[ [40, 41, 43, 45, 47, 50], [40, 39, 38, 36, 35, 33], [40, 42, 44, 47, 49, 52], [40, 43, 47, 52, 56, 61], [40, 38, 35, 32, 30, 28], ]" emphasis="median" width="150" height="40" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <EnsembleGhosts data="[[40, 43, 47, 52, 56, 61]]" title="One simulated path" width="160" height="40" /> ``` ```tsx `" > <EnsembleGhosts data="[ [4000, 4100, 4300, 4500, 4700, 5000], [4000, 3900, 3800, 3600, 3500, 3300], [4000, 4200, 4400, 4700, 4900, 5200], ]" locale="de-DE" title="Localized endpoints" width="160" height="40" /> ``` With one member, there is no bundle to show — the chart draws that single path as the representative, and the summary states its ending value rather than a spread. A member that contains a non-finite value (`NaN`, `Infinity`) is excluded entirely from ghost selection and the median, not gapped mid-path — a dev-only console warning flags it, since a partially invalid future usually means bad simulation output. ## Why this default [#why-this-default] A few faint paths and one emphasized, because a mean line hides that futures disagree in shape, not just endpoint — two ensembles can share an average and a final range while telling completely different stories along the way. The emphasized path defaults to the **real member** closest to the pointwise median, so the representative is an outcome that actually happened in the simulation, not a synthetic average of paths that never occurred (`emphasis="median"` draws that synthetic path instead). Selection and emphasis are deterministic — nothing about this chart varies between renders of the same data. `label="end"` (default) states the emphasized path's landing value in a right gutter; pass `label="none"` to drop it. The static frame is not a hypothetical-outcome plot. The **loop** — flipping through the members one at a time on hover — is the HOP, and it lives only in the interactive entry, gated on reduced motion with arrow-key stepping as the non-animated equivalent. ## Accessibility [#accessibility] The accessible name states the endpoint spread and the typical path — **"5 simulated paths end between 28 and 61; typical path ends near 50."** The interactive entry flips through the members (the HOP loop) on hover; with reduced motion, ←/→ step them discretely, and each member is announced with its endpoint. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[][]` | Ensemble members — 2–50 simulated paths. | | `ghosts` | `number` | Rendered member count (deterministic endpoint-rank selection). Default 8, cap 12. | | `emphasis` | `"nearest-median" \| "median" \| number` | A real median-like member, the synthetic median, or a pinned member. | | `endpoints` | `boolean` | Ghost endpoint dots — makes the final-value spread countable. | | `label` | `"end" \| "none"` | Emphasised path endpoint in a right gutter (default end). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # ErrorBudget (/docs/charts/error-budget) ErrorBudget answers "are we burning the error budget too fast to survive the window?". The budget remaining rides against the **steady-burn diagonal** — the pace that exactly spends the window — so "too fast" is legible at a glance: below the diagonal means you're outrunning your budget. Faster burn-rate reference lines (the Google-SRE 1×/6×/14.4× **convention**, not physics) sit below it as faint policy context. ```tsx <ErrorBudget data="[1, 0.96, 0.93, 0.9, 0.86, 0.83, 0.79, 0.75, 0.71, 0.67, 0.64, 0.62]" window="30" unit="day" label="remaining" title="Checkout SLO" width="260" height="30" /> ``` ## Install [#install] ```tsx import { ErrorBudget } from "@microcharts/react/error-budget"; <ErrorBudget data={remaining} window={30} title="Checkout SLO" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — an SLO error budget in a KPI card, a service list where each row is a budget, spotting a fast-burn before it exhausts the window. * **Avoid for** — a plain uptime series (Sparkline) or a one-number budget (Progress). ## Variants [#variants] ```tsx <ErrorBudget data={remaining} window={30} rates={[1]} />`" > <span className="inline-flex flex-col gap-1.5"> <ErrorBudget data="[1, 0.82, 0.6, 0.38, 0.18, 0.04, 0]" window="20" unit="day" title="Fast-burn" width="220" height="28" /> <ErrorBudget data="[1, 0.96, 0.93, 0.9, 0.86, 0.83, 0.79, 0.75, 0.71, 0.67, 0.64, 0.62]" window="30" rates="[1]" unit="day" title="Diagonal only" width="220" height="28" /> </span> ``` ```tsx `"> <ErrorBudget data="[1, 0.96, 0.93, 0.9, 0.86, 0.83, 0.79, 0.75, 0.71, 0.67, 0.64, 0.62]" window="30" unit="day" locale="de-DE" title="Localized" width="220" height="28" /> ``` `format` defaults to a percent formatter; with `locale` it follows that locale's own conventions for the remaining-budget label — "62 %" (space before the sign) under `de-DE` rather than the English "62%". ## Edge cases [#edge-cases] ```tsx `"> <ErrorBudget data="[]" title="No data yet" width="220" height="28" /> ``` ```tsx `"> <ErrorBudget data="[0.9]" window="30" unit="day" title="Day 1" width="220" height="28" /> ``` ```tsx `"> <ErrorBudget data="[1, 0.82, 0.6, 0.38, 0.18, 0.04, 0]" window="20" unit="day" title="Exhausted" width="220" height="28" /> ``` With no data the chart renders an empty root and the accessible name says **"No data."**; a single point still draws the diagonal, wedges, and endpoint, though `currentRate` (which needs a prior step) reads `0`. Once the remaining line reaches zero, an ✕ at that first zero-crossing replaces the endpoint dot, and the summary reads **"Budget exhausted at day 7 of 20."** instead of the normal remaining/rate sentence. Values are clamped to `0–1`, so nothing is ever drawn below the floor or above a full budget. ## Why this default [#why-this-default] Remaining-vs-diagonal, because "too fast" is only legible against the pace that exactly spends the window. The 1×/6×/14.4× reference lines are the SRE Workbook's multiwindow burn-rate alert **convention** — a policy default, never universal law — so `rates` is configurable and the lines render as faint background context, never data-colored. `currentRate` is the observed burn slope over the last `max(2, ⌈n/6⌉)` steps ÷ the steady slope; when the budget hits zero, an ✕ marks the crossing and the summary says so. ## Accessibility [#accessibility] The accessible name states the budget, the elapsed window, and the burn rate — **"62% of error budget remains at day 12 of 30 — burning at 0.6× the steady rate."**; an exhausted window reads "Budget exhausted at day N of M." The interactive entry steps the days and announces each step's remaining and local burn rate. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Budget remaining (0–1) per elapsed step; index 0 is 1.0. | | `window` | `number` | Total steps in the SLO window (default = data.length). | | `rates` | `number[]` | Burn-rate reference multiples (default the SRE 1×/6×/14.4× convention). | | `unit` | `string` | Period noun for the summary (default "day"). | | `label` | `"remaining" \| "none"` | Current budget % in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # EtaBar (/docs/charts/eta-bar) EtaBar answers "how long is this actually going to take, given how it has actually been going?". Its x-axis is time, not fraction: the solid part is the elapsed share of the predicted total, and the muted remainder is sized by the observed rate. When the rate drops, the remainder honestly grows — the download bar, told truthfully. ```tsx <EtaBar progress="0.64" elapsed="3.6" rate="0.18" etaFormat="(t) => `${Math.round(t)} min`" title="Export" width="280" height="16" /> ``` ## Install [#install] ```tsx import { EtaBar } from "@microcharts/react/eta-bar"; <EtaBar progress={0.64} elapsed={3.6} rate={0.18} etaFormat={(t) => `${Math.round(t)} min`} title="Export" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — download / export progress, job-queue ETAs, deploy timers. * **Avoid for** — fraction-only progress (Progress) or unbounded counters (Delta). ## Motion, and reduced motion [#motion-and-reduced-motion] The interactive entry eases the elapsed/remainder split (SVG `x`/`width`) to its new geometry whenever `progress`, `elapsed`, or `rate` change — the split only ever moves to a value computed from data you passed in on that render; it never interpolates ahead of an as-yet-unseen future frame. The transition lives in shared CSS (`.mc-eta-live rect`), so it inherits the shared `:where(.mc-root *) { transition: none }` reduced-motion block: with `prefers-reduced-motion: reduce` the bar snaps straight to each new split instead of easing. The live region re-announces the forecast on a throttle (`announceEvery`, default 10 s) so a fast-updating value doesn't spam a screen reader. ## Variants [#variants] ```tsx `"> <EtaBar progress="0.42" elapsed="10" rate="0.05" label="percent" title="Percent" width="280" height="16" /> ``` ```tsx `" > <EtaBar progress="0.42" elapsed="10" rate="0.05" locale="de-DE" title="Localized ETA" width="280" height="16" /> ``` Without an `etaFormat`, the remaining-time figure falls back to `format`/`locale` — under `de-DE` that's a decimal comma ("11,6") rather than the English decimal point ("11.6"). Pass `etaFormat` (as the hero example does) to add a unit; it always receives the raw number, so it can format the unit itself in whatever locale-aware way the caller needs. ## Edge cases [#edge-cases] ```tsx `"> <EtaBar progress="0.3" elapsed="40" rate="0" title="Stalled transfer" width="280" height="16" /> ``` ```tsx `" > <EtaBar progress="0.08" elapsed="30" rate="0.001" title="Barely started" width="280" height="16" /> ``` ```tsx `"> <EtaBar progress="1" elapsed="12" rate="0.1" title="Complete" width="280" height="16" /> ``` An explicit `rate` of `0`, or an absent `rate` from which no positive average can be derived from `elapsed`, renders the remainder as a diagonal-hatched texture instead of a solid bar — "unknown," not a hidden guess — and the summary says **"stalled"** rather than naming a duration. When the predicted remainder is far larger than the elapsed time, the done segment would round to an unreadable sliver, so the geometry clamps it to a visible 10% and adds a chevron marking the clamp as approximate. At `progress >= 1` the bar fills completely regardless of `rate`. ## Why this default [#why-this-default] The ETA label is the default because "how long?" is the question a plain progress bar pretends to answer. The remainder is sized by the observed rate, never linear interpolation — so a stalling transfer looks stalled instead of marching to a fake finish. When the rate is unknown or zero the remainder becomes an indeterminate texture and the summary says so, rather than inventing a countdown. ## Accessibility [#accessibility] The accessible name is the honest forecast — **"42% done; about 11.6 remaining at the current rate."** A stalled transfer reads **"30% done; stalled."** and a finished one **"Done."** The interactive entry re-announces on a throttle as the forecast changes. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `progress` (required) | `number` | Completed fraction 0–1. | | `elapsed` (required) | `number` | Time spent, any unit. | | `rate` | `number` | Progress per time unit — pass a recent-window rate. | | `label` | `"eta" \| "percent" \| "none"` | The remaining-time read is the product. | | `etaFormat` | `(t: number) => string` | Unit-bearing ETA label ("2 min") — the caller owns units. | | `announceEvery` | `number` | (interactive) Minimum ms between live-region announcements as the ETA streams (default 10000). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # EventRaster (/docs/charts/event-raster) EventRaster answers "when did each source fire — and do sources fire together, in sequence, or not at all?". Vertical bands reveal synchronization, diagonals reveal propagation, and sparse rows reveal silence. One tick is always one event — the only exception is the disclosed `overflow="bin"` mode for aliasing lanes. ```tsx <EventRaster data="[ { label: "api", events: [2, 5, 6, 14, 20, 21, 33, 40, 41, 48, 55] }, { label: "db", events: [3, 6, 15, 21, 34, 41, 55] }, { label: "cache", events: [6, 21, 41, 55] }, { label: "queue", events: [10, 30, 50] }, ]" title="Service events" width="300" height="56" /> ``` ## Install [#install] ```tsx import { EventRaster } from "@microcharts/react/event-raster"; <EventRaster data={services} title="Service events" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — service events across sources, agent steps, cron / sensor triggers. * **Avoid for** — a single lane (RugStrip) or continuous rates (Sparkline). ## Variants [#variants] ```tsx `"> <EventRaster data="[ { label: "api", events: [2, 5, 6, 14, 20, 21, 33, 40, 41, 48, 55] }, { label: "db", events: [3, 6, 15, 21, 34, 41, 55] }, { label: "cache", events: [6, 21, 41, 55] }, ]" emphasis="api" title="api emphasised" width="280" height="56" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <EventRaster data="[ { label: "api", events: [2, 5, 6, 14, 20, 33, 40, 48] }, { label: "db", events: [] }, ]" title="One quiet lane" width="220" height="32" /> ``` ```tsx i * 0.3) }]} overflow="bin" />`" > <EventRaster data="[{ label: "requests", events: Array.from({ length: 200 }, (_, i) => i * 0.3) }]" overflow="bin" title="High-rate lane" width="220" height="20" /> ``` ```tsx `"> <EventRaster data="[{ label: "boot", events: [0] }]" title="Single event" width="160" height="16" /> ``` ## Why this default [#why-this-default] Lanes stay aligned to a shared time domain because vertical banding — several sources firing at the same instant — is the phenomenon the chart exists to reveal. An empty lane is kept, not dropped: silence is signal. When a lane is so dense that ticks would alias into a solid smear, it switches to per-bucket counts shown as opacity, and the summary says which lanes were binned — the encoding change never hides. That is `overflow="bin"`, the default; `overflow="clip"` opts out and keeps one tick per event whatever the density. ## Accessibility [#accessibility] The accessible name summarises the field — **"3 lanes, 22 events; busiest api (11)."** The interactive entry roves lanes with ↑/↓ and events with ←/→, announcing each event's lane, time, and position within the lane. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label, events }[]` | One lane per source. | | `emphasis` | `string` | Accents one lane — the sync read. | | `labels` | `boolean` | Left-gutter lane names (on ≤ 8 lanes). | | `overflow` | `"bin" \| "clip"` | Aliasing lanes bin to counts (disclosed). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # EventTimeline (/docs/charts/event-timeline) EventTimeline answers "what happened when, and for how long?" — uptime windows, on-call shifts, release spans and incident points on one row. Diamonds mark instants, rects mark durations: the type distinction is a shape, so it survives 12 px where color coding wouldn't. ```tsx `" > <EventTimeline data="[ { start: Date.UTC(2026, 5, 3, 1), end: Date.UTC(2026, 5, 3, 5), label: "Freeze", kind: "accent" }, { start: Date.UTC(2026, 5, 3, 6), end: Date.UTC(2026, 5, 3, 15), label: "Healthy", kind: "positive" }, { start: Date.UTC(2026, 5, 3, 11), label: "Incident", kind: "negative" }, { start: Date.UTC(2026, 5, 3, 16), end: Date.UTC(2026, 5, 3, 18), kind: "negative" }, { start: Date.UTC(2026, 5, 3, 20), label: "Release" }, ]" domain="[Date.UTC(2026, 5, 3), Date.UTC(2026, 5, 4)]" title="API uptime" width="240" height="30" /> ``` ## Install [#install] ```tsx import { EventTimeline } from "@microcharts/react/event-timeline"; <EventTimeline data={windows} domain={today} title="API uptime" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — per-service uptime rows, on-call shifts and release windows in cards. * **Avoid for** — more than \~12 items, or aggregated durations (MiniBar of totals). ## Variants [#variants] ```tsx `" > <EventTimeline data="[ { start: Date.UTC(2026, 5, 3, 6), end: Date.UTC(2026, 5, 3, 15), label: "Healthy", kind: "positive", }, { start: Date.UTC(2026, 5, 3, 11), label: "Incident", kind: "negative" }, ]" domain="[Date.UTC(2026, 5, 3), Date.UTC(2026, 5, 4)]" now="Date.UTC(2026, 5, 3, 21)" title="With now" width="240" height="30" /> ``` ```tsx `" > <EventTimeline data="[ { start: Date.UTC(2026, 5, 3, 6), end: Date.UTC(2026, 5, 3, 15), label: "Healthy", kind: "positive", }, { start: Date.UTC(2026, 5, 3, 16), end: Date.UTC(2026, 5, 3, 18), label: "Deploy", kind: "accent", }, ]" domain="[Date.UTC(2026, 5, 3), Date.UTC(2026, 5, 4)]" label="spans" width="280" height="26" title="Labeled spans" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <EventTimeline data="[ { start: Date.UTC(2026, 5, 3, 9), label: "Deploy" }, { start: Date.UTC(2026, 5, 3, 14), label: "Alert", kind: "negative" }, { start: Date.UTC(2026, 5, 3, 18), label: "Resolved", kind: "positive" }, ]" domain="[Date.UTC(2026, 5, 3), Date.UTC(2026, 5, 4)]" title="Today's events" width="220" height="16" /> ``` ```tsx `" > <EventTimeline data="[{ start: Date.UTC(2026, 5, 2, 20), end: Date.UTC(2026, 5, 3, 10), label: "Maintenance" }]" domain="[Date.UTC(2026, 5, 3), Date.UTC(2026, 5, 3, 6)]" title="Clipped window" width="220" height="16" /> ``` ## Why this default [#why-this-default] Duration is length on a linear time axis — never log or compressed time. Items that overlap the window edge are clipped flat (honest partial visibility); fully-outside items are excluded with a dev warning. Overlapping spans render translucent in data order — a legibility device, not an encoding; the exact intervals live in the announcements. ## Accessibility [#accessibility] The accessible name is the coverage read — **"2 spans covering 46% of the window; 0 events."** — where coverage merges intervals first, so overlaps never double-count. The interactive entry cycles items chronologically: spans announce **"Freeze: Jun 3, 01:00 to Jun 3, 05:00 — 4h."**, instants **"Incident: Jun 3, 11:00."** The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ start; end?; label?; kind? }[]` | Spans (with end) and point events (without), ms epoch or Date. | | `domain` | `[start, end]` | The window — fix it across rows for small multiples. | | `now` | `number \| Date` | Current-moment tick; authored, never implicit. | | `label` | `"none" \| "spans"` | Centered in-span labels with deterministic drop-out. | | `dateFormat` | `Intl.DateTimeFormatOptions \| (d: Date) => string` | (interactive) Announced timestamp format for focused events (defaults to a locale date-time). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # FatDigits (/docs/charts/fat-digits) FatDigits answers "which numbers in this dense column are big, before I read them?" The numeral is always the exact value; font *weight* is a second, redundant channel — five (or three) ordinal tiers mapped from your `domain` — so the large numbers pop preattentively as you scan a column. Weight is never the primary read: it is ordinal and coarse, and the number is right there. ```tsx <span style="{ display: "inline-flex", flexDirection: "column", alignItems: "flex-end", gap: 2 }" className="tabular-nums"> <FatDigits value="1204" domain="[0, 2100]" summary="false" fontSize="16" /> <FatDigits value="318" domain="[0, 2100]" summary="false" fontSize="16" /> <FatDigits value="2100" domain="[0, 2100]" summary="false" fontSize="16" /> <FatDigits value="76" domain="[0, 2100]" summary="false" fontSize="16" /> </span> ``` ## Install [#install] ```tsx import { FatDigits } from "@microcharts/react/fat-digits"; <FatDigits value={1204} domain={[0, 2100]} title="Revenue" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a dense numeric table column you scan for the big ones, a KPI number that should carry its own magnitude, or an amount in a sentence. * **Avoid for** — trends (Sparkline), proportions (Progress), or comparisons (MiniBar). ## Variants [#variants] ```tsx <FatDigits value={1204} domain={[0, 2100]} tiers={3} />`" > <span className="inline-flex gap-5 items-center"> <FatDigits value="1902" encode="digit" fontSize="18" /> <FatDigits value="1204" domain="[0, 2100]" tiers="3" fontSize="18" /> </span> ``` `format` also takes `Intl.NumberFormatOptions` — the numeral itself follows the locale's own grouping and decimal marks. ```tsx `" > <FatDigits value="12040" domain="[0, 20000]" format="{ style: "currency", currency: "EUR", maximumFractionDigits: 0 }" locale="de-DE" fontSize="18" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <FatDigits value="1204" fontSize="18" /> ``` ```tsx `"> <FatDigits value="Number.NaN" domain="[0, 2100]" fontSize="18" title="Missing" /> ``` A non-finite value renders nothing (no numeral, no weight) and reports **"No data."** rather than guessing a tier. ## Why this default [#why-this-default] Value mode with five tiers is the default because scanning a column is the use case, and five is the most weight steps that stay discriminable at text size. Always pass a `domain` — without one a lone number has no tier to sit in, so it renders at the middle weight and means nothing. `encode="digit"` instead weights each digit by its own magnitude, a redundancy that helps scan long ids and amounts. This is adapted from the FatFonts idea: the research encodes magnitude as glyph ink area with a custom font; shipping a font would add a dependency, so weight tiers on the inherited font carry the ordinal instead — the numeral is always the exact value. On a font without many weights the browser snaps to the nearest available face, so fewer of the tiers stay visually distinct. ## Accessibility [#accessibility] The accessible name is the exact value and its tier — **"1,204 — tier 3 of 5."** — and in digit mode just the number, since each digit carries its own weight. The interactive entry eases the weight to its new tier on variable fonts (it snaps otherwise) with no layout shift, and announces the value and tier through a polite live region. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The number (always the exact value). | | `domain` | `readonly [number, number]` | Maps value to a weight tier — always pass one. | | `encode` | `"value" \| "digit"` | value weights the whole numeral; digit weights each digit by its own magnitude. | | `tiers` | `3 \| 5` | Weight steps (default 5). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # FillWord (/docs/charts/fill-word) FillWord answers "how far along is this named task?" by making the label *be* the bar. A muted word is overlaid with an accent copy of itself, clipped to the value fraction of the word's own inked extent — so 50% visually bisects the word. The fill is a percentage of the glyphs you see, never of a hidden wider track. It trades some precision for a read that needs no separate label. ```tsx <FillWord word="uploading" value="0.62" title="Upload" fontSize="18" /> ``` ## Install [#install] ```tsx import { FillWord } from "@microcharts/react/fill-word"; <FillWord word="uploading" value={0.62} /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a labelled progress read in a sentence or cell, a sync/upload status where the label names the task, or a quota/TTL where the word is the metric. * **Avoid for** — precise percentages (Progress), trends (Sparkline), or many parallel bars (MiniBar). ## Variants [#variants] ```tsx <FillWord word="storage" value={0.4} label="value" />`" > <span className="inline-flex gap-5 items-center"> <FillWord word="expiring" value="0.7" mode="drain" fontSize="16" /> <FillWord word="storage" value="0.4" label="value" fontSize="16" /> </span> ``` ## Edge cases [#edge-cases] ```tsx <FillWord word="uploading" value={1} />`" > <span className="inline-flex gap-5 items-center"> <FillWord word="uploading" value="0" fontSize="16" title="0%" /> <FillWord word="uploading" value="1" fontSize="16" title="100%" /> </span> ``` At 0% the word is entirely the muted track; at 100% it is entirely accent ink — both ends are honest limits of the same clip, not a special case. ```tsx `"> <FillWord value="0.5" fontSize="16" title="Empty" /> ``` An empty `word` renders nothing and reports **"No data."** — there is no label to be the bar. ## Why this default [#why-this-default] Fill (not drain) is the default because progress is the ninety-percent case — a word filling as a step completes. `mode="drain"` empties the ink from the left as the value rises, the remaining-time story that fill cannot tell (TTLs, expiring sessions). Because glyph ink is uneven, fine reads are ±5% — the fill edge lands between letters, not on an exact tick. When you need the number, add `label="value"` for the percent alongside, or reach for `Progress` when precision is the point. ## Accessibility [#accessibility] The accessible name names the task and its state — **"storage: 40% complete."** — or, in drain mode, where `value` is the fraction already drained, **"expiring: 30% remaining."** for `value={0.7}`. An empty word reads "No data." The interactive entry glides the ink edge with a reduced-motion-gated clip-path transition and announces changes through a polite live region, throttled to at most once a second so a streaming value never spams. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `word` (required) | `string` | The text that is the chart. | | `value` (required) | `number` | Fraction 0–1 (clamped). | | `mode` | `"fill" \| "drain"` | fill grows the ink (complete); drain empties it (remaining / TTL). | | `label` | `"none" \| "value"` | Append the percent numeral after the word. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # FoldedDayBand (/docs/charts/folded-day-band) FoldedDayBand answers "what does a typical period look like — and is the current one typical?". It folds many days (or weeks, or any cycle) onto a single period axis and shows the median with 25–75 and 5–95 percentile envelopes. Drop in a `today` overlay and the chart answers the second question: is right now inside the usual band, or an outlier? ```tsx 40 + 42 _ Math.max(0, 1 - Math.abs(h - 14) / 10); const observations = Array.from({ length: 14 }, (\_d, d) => Array.from({ length: 24 }, (\_h, h) => ({ t: d _ 24 + h, value: Math.round(curve(h) + Math.sin(d + h) \* 8), })), ).flat(); const today = Array.from({ length: 24 }, (\_h, h) => ({ t: h, value: Math.round(curve(h) + 14), })); <FoldedDayBand data={observations} today={today} title="Typical day" />`" > <FoldedDayBand data="Array.from({ length: 14 }, (_d, d) => Array.from({ length: 24 }, (_h, h) => ({ t: d * 24 + h, value: Math.round(40 + 42 * Math.max(0, 1 - Math.abs(h - 14) / 10) + Math.sin(d + h) * 8) }))).flat()" today="Array.from({ length: 24 }, (_h, h) => ({ t: h, value: Math.round(40 + 42 * Math.max(0, 1 - Math.abs(h - 14) / 10) + 14) }))" title="Typical day" width="300" height="40" /> ``` ## Install [#install] ```tsx import { FoldedDayBand } from "@microcharts/react/folded-day-band"; <FoldedDayBand data={observations} today={today} title="Typical day" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — typical-day traffic or load profiles, on-call or energy capacity planning. * **Avoid for** — a raw time series (Sparkline) or a single period with nothing to fold. ## Variants [#variants] ```tsx <FoldedDayBand data={observations} format={{ minimumFractionDigits: 1, maximumFractionDigits: 1 }} locale="de-DE" />`" > <span className="inline-flex flex-col gap-3"> <FoldedDayBand data="Array.from({ length: 14 }, (_d, d) => Array.from({ length: 24 }, (_h, h) => ({ t: d * 24 + h, value: Math.round(40 + 42 * Math.max(0, 1 - Math.abs(h - 14) / 10) + Math.sin(d + h) * 8), })), ).flat()" percentiles="[[25, 75]]" title="Middle half only" width="300" height="40" /> <FoldedDayBand data="Array.from({ length: 14 }, (_d, d) => Array.from({ length: 24 }, (_h, h) => ({ t: d * 24 + h, value: Math.round(40 + 42 * Math.max(0, 1 - Math.abs(h - 14) / 10) + Math.sin(d + h) * 8), })), ).flat()" format="{ minimumFractionDigits: 1, maximumFractionDigits: 1 }" locale="de-DE" title="Localized peak" width="220" height="32" /> </span> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, the accessible summary's fold position and peak value follow that locale's own decimal mark ("14,0" in German, not "14.0"). The band and median line themselves don't change shape; only the announced numbers are localized. ## Edge cases [#edge-cases] ```tsx `"> <FoldedDayBand data="[{ t: 3, value: 10 }]" title="Single observation" width="160" height="32" /> ``` ```tsx ({ t: i, value: 7 }))} />`" > <FoldedDayBand data="Array.from({ length: 48 }, (_v, i) => ({ t: i, value: 7 }))" title="Flat" width="200" height="32" /> ``` A single observation reports a real accessible name (median and peak both equal that one value) but has no width to fold across, so nothing visibly paints — the chart is accessible-first even when there's too little data to draw. Identical values across every bin still render as a flat line, distinct from an empty `data` array, which renders nothing and announces "No data." ## Why this default [#why-this-default] Two envelopes plus a median is the typical-day grammar that clinical glucose profiles standardized on. The envelopes come from real per-bin quantiles — never smoothed across bins into a shape the data doesn't support — and the outer boundary fades so 5–95 doesn't read as a hard limit. When a bin has too few observations the band collapses to the median there rather than inventing a width. ## Accessibility [#accessibility] The accessible name reports the peak — **"Median peaks at 14 (82.5)."** The interactive entry roves the folded axis with ←/→, announcing the median and middle-half at each position. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ t, value }[]` | Raw observations across many periods. | | `period` | `number` | Fold length (168 folds a week). | | `today` | `{ t, value }[]` | The current period overlaid. | | `percentiles` | `[number, number][]` | Percentile pairs, outermost last. | | `bins` | `number` | Fold-axis resolution (default 24). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # ForecastCone (/docs/charts/forecast-cone) ForecastCone answers "will we land where we need to?". History is a solid line; the forecast is a fan of prediction bands that **widen over the horizon**, with a **dashed** median — because an estimate should never render as fact. The whole point of a fan chart is visible confidence decay, so three rules are not style options: at most two bands (50/80 — a 95% band reads as false tail confidence at micro scale), the median is always dashed, and a cone that fails to widen is flagged, never quietly inflated. ```tsx <ForecastCone data="[30, 32, 31, 34, 36, 35, 38]" forecast="{ mid: [39, 40, 41, 42], p80: [ [36, 42], [35, 45], [34, 50], [33, 55], ], p50: [ [37, 41], [37, 43], [36, 46], [35, 49], ], }" target="45" label="landing" title="Q4 revenue" width="260" height="28" /> ``` ## Install [#install] ```tsx import { ForecastCone } from "@microcharts/react/forecast-cone"; <ForecastCone data={history} forecast={forecast} target={45} title="Q4 revenue" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a "will we hit Q4?" forecast in a KPI card, a projection with honest uncertainty in a sentence, band-vs-target landing reads. * **Avoid for** — a forecast with no uncertainty (Sparkline) or one estimate's spread (GradedBand). ## Variants [#variants] ```tsx `" > <span className="inline-flex flex-col gap-1.5"> <ForecastCone data="[30, 32, 31, 34, 36, 35, 38]" forecast="{ mid: [39, 40, 41, 42], p80: [ [36, 42], [35, 45], [34, 50], [33, 55], ], }" title="Single band" width="220" height="26" /> <ForecastCone data="[30, 32, 31, 34, 36, 35, 38]" forecast="{ mid: [39, 40, 41, 42], p80: [ [36, 42], [35, 45], [34, 50], [33, 55], ], p50: [ [37, 41], [37, 43], [36, 46], [35, 49], ], }" target="50" title="Vs a higher target" width="220" height="26" /> </span> ``` ```tsx `" > <ForecastCone data="[3000, 3200, 3100, 3400, 3600, 3500, 3800]" forecast="{ mid: [3900, 4000, 4100, 4200], p80: [ [3600, 4200], [3500, 4500], [3400, 5000], [3300, 5500], ], }" format="{ style: "currency", currency: "EUR", maximumFractionDigits: 0 }" locale="de-DE" title="Localized forecast" width="220" height="26" /> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, the in-chart landing label and the accessible summary's median, interval, and target numbers all follow that locale's own grouping and currency placement (the label above reads "4.200 €", not "€4,200"). ## Edge cases [#edge-cases] ```tsx `" > <ForecastCone data="[]" forecast="{ mid: [10, 12, 14], p80: [ [8, 12], [8, 15], [7, 19], ], }" title="No history" width="160" height="26" /> ``` ```tsx `" > <ForecastCone data="[10, 11]" forecast="{ mid: [12, 13, 14], p80: [ [9, 15], [10, 14], [11, 13], ], }" title="Narrowing input" width="160" height="26" /> ``` With no history the cone still draws from the first forecast point, and the accessible summary quietly drops its "from N today" clause instead of naming a value that doesn't exist. A cone whose bands narrow instead of widen is an input-honesty failure — it renders exactly as supplied (never auto-inflated to look right) and logs a one-time dev warning so the mistake surfaces in development rather than silently misleading a reader. ## Why this default [#why-this-default] 50/80 bands, not 95, because micro-scale tails invite overreading — a 95% band paints false confidence about the extremes. The median is dashed so it never reads as a committed number, and the cone must visibly widen: if the supplied bands don't (they narrow, or stay flat), that is an input-honesty failure the component surfaces rather than papering over — a forecast whose uncertainty doesn't grow with the horizon is misrepresenting confidence decay. ## Accessibility [#accessibility] The accessible name states the median, the horizon interval, today's actual, and — with a target — whether the band clears it: **"Median forecast 42 by week 11 (80% between 33 and 55), from 38 today. The 80% band straddles the 50 target."**. The interactive entry is region-aware: history points announce a value, forecast points announce the median and 80% interval. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Historical actuals. | | `forecast` (required) | `{ mid: number[]; p80: [lo,hi][]; p50?: [lo,hi][] }` | Median + prediction bands (at most 2: 50/80). | | `target` | `number` | The landing reference the cone must clear (adds a clearance clause). | | `unit` | `string` | Period noun for the summary (default "week"). | | `label` | `"landing" \| "none"` | Median endpoint value in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Funnel (/docs/charts/funnel) Funnel answers "where does the pipeline leak?". Stepped rectangles, zero-anchored — never the classic tapered silhouette, which interpolates data that doesn't exist. The drop *between* neighbors is the read. ```tsx <Funnel data="[ { label: "Visitors", value: 12400 }, { label: "Signups", value: 5704 }, { label: "Activated", value: 2730 }, { label: "Paid", value: 1116 }, ]" title="Signup funnel" width="220" height="66" /> ``` ## Install [#install] ```tsx import { Funnel } from "@microcharts/react/funnel"; <Funnel data={stages} title="Signup funnel" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — per-campaign funnels in table cells, conversion bridges in cards. * **Avoid for** — unordered categories (MiniBar) or more than 6 stages. ## Variants [#variants] ```tsx `" > <Funnel data="[ { label: "Visitors", value: 12400 }, { label: "Signups", value: 5704 }, { label: "Paid", value: 1116 }, ]" mode="rate" title="Rate" width="220" height="66" /> ``` ```tsx `" > <Funnel data="[ { label: "Visitors", value: 12400 }, { label: "Signups", value: 5704 }, { label: "Activated", value: 2730 }, { label: "Paid", value: 1116 }, ]" highlight="Activated" title="The leak" width="220" height="66" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <Funnel data="[{ label: "Visitors", value: 8000 }]" title="Single stage" width="120" height="40" /> ``` ```tsx `" > <Funnel data="[ { label: "Trial", value: 900 }, { label: "Churned", value: 420 }, { label: "Win-back", value: 610 }, ]" title="Re-engagement funnel" width="220" height="56" /> ``` ## Why this default [#why-this-default] `rate` always normalizes to stage 1, never to the previous stage — per-stage rates hide compounding loss. A stage larger than its predecessor (re-engagement funnels) renders truthfully and the summary appends the inversion. The connectors and zero-anchored columns keep the read a measurement, not a shape. ## Accessibility [#accessibility] The accessible name is the conversion story — **"4 stages, 12,400 to 1,116 — overall 9%."**, plus **"Stage 3 exceeds stage 2."** when a pipeline inverts. The interactive entry roves stages (**"Activated: 2,730 — 22% of Visitors."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value }[]` | Ordered stages. | | `mode` | `"absolute" \| "rate"` | Rate = % of the FIRST stage (never the previous). | | `connectors` | `boolean` | Retained-share slats between stages. | | `label` | `"none" \| "percent" \| "value"` | Above each column (deterministic drop-out; default percent). | | `highlight` | `number \| string` | Accent the leak stage. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # GardenGrid (/docs/charts/garden-grid) GardenGrid answers "what's the rhythm of activity over time?" the way ActivityGrid does — but with a single ink. Instead of color, dot **area** carries a five-step ordinal, so the rhythm reads in grayscale and print where a color heatmap would collapse. The radius is √-quantized so perceived area steps evenly. A zero cell is a hairline ring (present, but quiet); a `null` cell is nothing at all, because "missing" is not "zero". ```tsx <GardenGrid data="[12, 20, 8, 0, 15, 28, 34, 5, 0, 22, 18, 9, 3, 0, 24, 30, 11, 6, 19, 0, 26]" unit="weeks" title="Activity" cell="11" /> ``` ## Install [#install] ```tsx import { GardenGrid } from "@microcharts/react/garden-grid"; <GardenGrid data={weeks} title="Activity" unit="weeks" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a contribution or activity rhythm you print or read in grayscale, a per-repo or per-team activity strip, or any calendar-shaped intensity where color isn't available. * **Avoid for** — exact per-cell values (ActivityGrid with hover, or HeatStrip) or trends (Sparkline). ## Variants [#variants] ```tsx <GardenGrid data={weeks} empty="blank" />`" > <span className="inline-flex flex-col gap-3"> <GardenGrid data="[12, 20, 8, 0, 15, 28, 34, 5, 0, 22, 18, 9]" rows="1" cell="11" /> <GardenGrid data="[12, 20, 8, 0, 15, 28, 34, 5, 0, 22, 18, 9, 3, 0]" empty="blank" cell="11" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <GardenGrid data="[]" title="No history" cell="11" /> ``` ```tsx `"> <GardenGrid data="[0, 0, 0, 0, 0, 0, 0]" title="Quiet week" cell="11" /> ``` ```tsx `"> <GardenGrid data="[5, null, 8, null, null, 3]" title="Gaps" cell="11" /> ``` ```tsx `"> <GardenGrid data="[12]" title="One" cell="11" /> ``` ## Why this default [#why-this-default] Rings for zero are the default because print and grayscale lose the zero-versus-missing distinction that color grids get for free — this chart exists for exactly that medium, so it makes "present but quiet" visible. The radius is √-quantized so **area** carries the ordinal; a linear radius map would exaggerate the highs quadratically. The steps are ordinal, not values — the interactive entry announces a cell's step rather than implying a precise read, and `ActivityGrid` is the color twin when exact values matter. ## Accessibility [#accessibility] The accessible name summarizes the rhythm — **"12 periods; peak 34, 10 active."** The interactive entry walks the grid in 2-D with the arrow keys (or hover), announcing each cell as its ordinal step — **"3 of 21: 8, step 2 of 5."** — never a false-precise value, since dot area reads to a step, not a number. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | Binned values; null = missing. | | `rows` | `number` | Grid rows (default 7); 1 = strip. | | `steps` | `3 \| 5` | Radius quantization steps (default 5). | | `empty` | `"outline" \| "blank"` | How zero cells render (default outline). | | `unit` | `string` | Noun for the summary count (default "periods"). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # GradeProfile (/docs/charts/grade-profile) GradeProfile answers "how hard is this route, and where does it bite?" Each segment between two points is filled from the baseline and coloured by its grade — gentle to brutal — with the elevation ridge riding on top. The steepest pitch is called out, so the wall in the route is the first thing you see. **How to read it** — colour is a *quantized* grade bin, never a smooth ramp: flats and every descent take the faint band, then a mid tone, the negative colour, and the darkest fill for the brutal pitches. Height is the elevation ridge for shape; the encoded channel is the colour, and the interactive readout gives the exact grade. ```tsx <GradeProfile data="[ { d: 0, elev: 800 }, { d: 100, elev: 809 }, { d: 250, elev: 812 }, { d: 350, elev: 817 }, { d: 500, elev: 835 }, { d: 700, elev: 833 }, { d: 900, elev: 865 }, ]" format="{ style: "unit", unit: "meter", unitDisplay: "short" }" title="Queen stage" width="240" height="48" /> ``` `d` and `elev` must share a unit (both metres, say) so that grade — rise ÷ run — is a true percent. Distance need only be monotonic; the values themselves can be any scale. ## Install [#install] ```tsx import { GradeProfile } from "@microcharts/react/grade-profile"; <GradeProfile data={trail} format={(n) => `${n} m`} title="Queen stage" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — route and climb profiles (cycling, running, hiking); showing *where* the hard pitches fall. * **Avoid for** — a single elevation series (Sparkline), or an unordered track (distance must be monotonic). ## Variants [#variants] ```tsx `" > <GradeProfile data="[ { d: 0, elev: 800 }, { d: 250, elev: 812 }, { d: 500, elev: 835 }, { d: 700, elev: 833 }, { d: 900, elev: 865 }, ]" label="none" title="No label" width="240" height="44" /> ``` ```tsx `" > <GradeProfile data="[ { d: 0, elev: 800 }, { d: 100, elev: 809 }, { d: 350, elev: 817 }, { d: 500, elev: 835 }, { d: 900, elev: 865 }, ]" bins="[5, 8, 12]" format="{ style: "unit", unit: "meter", unitDisplay: "short" }" title="Custom bins" width="240" height="44" /> ``` ```tsx `" > <GradeProfile data="[ { d: 0, elev: 600 }, { d: 2000, elev: 780 }, { d: 5000, elev: 1150 }, { d: 8000, elev: 1400 }, { d: 12000, elev: 1850 }, ]" format="{ maximumFractionDigits: 0 }" locale="de-DE" title="Alpine stage" width="240" height="48" /> ``` `format` accepts `Intl.NumberFormatOptions` (with a `locale`) or a formatting function, and applies to **distance and elevation** numbers in the summary and readout — not grade. Grades are always percent-encoded; the locale still decides the decimal mark: the alpine profile above reads **"12.000, 1.250 gain; steepest 12,3% at 3.500."** in German. ## Edge cases [#edge-cases] ```tsx \`\${n} m\`} title="Descent" />`" > <GradeProfile data="[ { d: 0, elev: 900 }, { d: 300, elev: 840 }, { d: 600, elev: 780 }, ]" format="{ style: "unit", unit: "meter", unitDisplay: "short" }" title="Descent" width="200" height="44" /> ``` ```tsx `" > <GradeProfile data="[ { d: 0, elev: 100 }, { d: 100, elev: 120 }, { d: 200, elev: NaN }, { d: 300, elev: 160 }, ]" title="Partial track" width="200" height="44" /> ``` A descent-only route has no climb to grade, so no pitch is emphasised and the summary reports **"600 m, no real climb."** — climbing difficulty is the whole story, so descents always take the gentlest colour rather than borrowing a climb's. A non-finite elevation breaks the profile into a gap: the segments touching it drop out and the ridge splits, so a missing reading never invents a grade. A flat route reports the "no real climb" sentence too, and a single point has no segment to grade at all, so its accessible name falls back to **"No data."** ## Why this default [#why-this-default] Two decisions carry the chart. Grade is **quantized** into bins, not drawn as a continuous colour ramp — a route reads as "gentle / rolling / steep / wall", categories a rider can act on, instead of a gradient nobody can decode at a glance. And the default `bins` of `[3, 6, 10]` percent match how climbs are actually described, with the steepest pitch labelled so the hardest moment is never buried. Below 72 pixels wide the four bins collapse to a simple flat-versus-climb read, because the finer classes stop being separable there. ## Accessibility [#accessibility] The accessible name states the route's shape in words — **"900, 67 gain; steepest 16% at 800."** — distance, total climb, and where the hardest pitch falls, none of it dependent on colour. The interactive entry announces each pitch as you rove it (`←`/`→`), giving the true grade and the cumulative climb, so the encoding never has to be learned to be used. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ d: number; elev: number }[]` | Distance + elevation, monotonic in d, same unit so grade is a true percent. | | `bins` | `[number, number, number]` | Ascending grade-% thresholds (always percent) that quantize the four difficulty bins. | | `format` | `Intl.NumberFormatOptions \| (n) => string` | Formats distance and elevation in the summary and readout; grades always render as percent. | | `label` | `"max" \| "none"` | Mark the steepest pitch, or render the profile alone. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # GradedBand (/docs/charts/graded-band) GradedBand answers "how sure are we about this one number?". Nested central intervals are graded by opacity, with a median tick. It is **never** a bar from zero — a bar with an error bar induces edge-literalism bias, so this form exists precisely to avoid it. Opacity maps to probability level and nothing else. ```tsx <GradedBand data="Array.from({ length: 160 }, (_, i) => 21 + Math.round(9 * Math.sin(i) + 6 * Math.sin(i * 2.3)))" label="median" title="Forecast estimate" width="240" height="16" /> ``` ## Install [#install] ```tsx import { GradedBand } from "@microcharts/react/graded-band"; <GradedBand data={posterior} label="median" title="Forecast estimate" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a forecast with its uncertainty, estimate-vs-actual in a KPI card, posterior summaries. * **Avoid for** — countable odds (QuantileDots) or a forecast over time (ForecastCone). ## Variants [#variants] ```tsx 21 + Math.round(9 * Math.sin(i) + 6 * Math.sin(i * 2.3)), ); <GradedBand data={posterior} value={28} /> <GradedBand data={posterior} softEdge />`" > <span className="inline-flex flex-col gap-1.5"> <GradedBand data="Array.from( { length: 160 }, (_, i) => 21 + Math.round(9 * Math.sin(i) + 6 * Math.sin(i * 2.3)), )" value="28" title="Estimate vs actual" width="200" height="14" /> <GradedBand data="Array.from( { length: 160 }, (_, i) => 21 + Math.round(9 * Math.sin(i) + 6 * Math.sin(i * 2.3)), )" title="Soft edge" width="200" height="14" /> </span> ``` ```tsx (21 + Math.round(9 * Math.sin(i) + 6 * Math.sin(i * 2.3))) / 10, ); <GradedBand data={drift} label="median" locale="de-DE" />`" > <GradedBand data="Array.from( { length: 160 }, (_, i) => (21 + Math.round(9 * Math.sin(i) + 6 * Math.sin(i * 2.3))) / 10, )" label="median" locale="de-DE" title="Localized median" width="200" height="14" /> ``` With a `locale`, the median label and the accessible summary follow that locale's decimal mark — the label above renders "2,2", not "2.2". ## Edge cases [#edge-cases] ```tsx `" > <GradedBand data="[42, 42, 42, 42, 42, 42]" title="No spread" width="200" height="14" /> ``` The accessible name for that strip is **"Point value 42, no interval."** — a degenerate sample is announced as a point estimate, never dressed up as certainty about a range. ```tsx `" > <GradedBand data="[19, 20, 21, 21, 22, 22, 23, 23, 24, 26]" value="48" title="Forecast miss" width="200" height="14" /> ``` ## Why this default [#why-this-default] Nested central intervals graded by opacity — never a bar from zero. A bar with an error whisker invites reading the bar's end as "the answer" and the whisker as noise; the graded band has no endpoint to over-read, so opacity maps to probability and nothing else. Inner intervals are clipped inside their outer, so quantile rounding can never invert the nesting. ## Accessibility [#accessibility] The accessible name states the median and the innermost + outermost intervals — for the forecast above that's **"Median 22; 50% within 15–27, 95% within 8–36."** The interactive entry roves the band edges and announces each interval's coverage and bounds. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Sample / posterior draws; the component derives the intervals. | | `levels` | `number[]` | 1–3 nested central intervals (default [50, 80, 95]). | | `value` | `number` | Observed value overlaid as a dot. | | `softEdge` | `boolean` | Fade past the outer band — 'this is approximate'. | | `label` | `"median" \| "none"` | States the median in a right gutter (default none). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # HeartbeatBlip (/docs/charts/heartbeat-blip) HeartbeatBlip answers "is it alive, and how busy?" at a glance. Each event in the recent window is an ECG-style spike; in the interactive entry the trace sweeps left in real time and a new event blips in at the right edge, so the rate you see **is** the event rate. Every spike is one real event — never a synthesized pulse on a timer — and an empty, flat baseline is the down signal, carried by shape, not color. ```tsx <HeartbeatBlip events="[97000, 92000, 85000, 70000, 55000, 48000]" now="100000" title="Requests" width="90" /> ``` ## Install [#install] ```tsx import { HeartbeatBlip } from "@microcharts/react/heartbeat-blip"; // pass 'now' from your data layer — never Date.now() in a server render <HeartbeatBlip events={eventTimestamps} now={serverNow} title="Requests" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## Motion, and reduced motion [#motion-and-reduced-motion] The trace advances in real time so old spikes drift left and new events enter at the right — the liveness comes from watching the blips arrive. This is the deliberate idle-loop exception, allowed because the loop parameter (elapsed time) is the datum. It pauses off-screen (a shared observer) and, under `prefers-reduced-motion`, does not sweep at all: the static strip simply re-renders on each data change — the same information, discretely updated. The one rule this chart must never break: **a flat service never gets a fake pulse.** Every spike is a real event; when the window empties, the baseline goes flat and stays flat. ## When to use it [#when-to-use-it] * **Good for** — at-a-glance liveness of a service or stream, request rate in a header, or per-service liveness in a status table. * **Avoid for** — exact event counts (`Seismogram`, `EventTimeline`), a continuous level (`BreathingDot`), or long-term trends (`Sparkline`). ## Sizing [#sizing] `width` and `height` are viewBox units that also set the rendered pixel box — they default to `60 × 16`, sized to sit in a status table row or a header. Omit them and drive the width from CSS to fill a column; the viewBox keeps the aspect ratio. `window` sets how much time the strip covers, which changes the density of the trace rather than its box. ## Variants [#variants] ```tsx <HeartbeatBlip events={[]} now={serverNow} />`" > <span className="inline-flex gap-6 items-center"> <HeartbeatBlip events="[97000, 92000, 85000, 70000, 55000, 48000]" now="100000" label="count" width="90" summary="false" /> <HeartbeatBlip events="[]" now="100000" width="90" summary="false" /> </span> ``` ```tsx `" > <HeartbeatBlip events="[97000, 92000, 85000]" now="100000" label="count" format="{ useGrouping: false }" locale="de-DE" title="Requests" width="90" /> ``` `format`/`locale` only reach the `label="count"` numeral — the accessible summary's count is a plain integer (never run through the formatter), and the in-chart spikes never carry text, so there's nothing else to localize. ## Edge cases [#edge-cases] ```tsx `"> <HeartbeatBlip events="[]" now="100000" title="Requests" width="90" /> ``` ```tsx `"> <HeartbeatBlip events="[97000, Number.NaN, 92000]" now="100000" title="Requests" width="90" /> ``` ```tsx `" > <HeartbeatBlip events="[95000, 10000]" now="100000" title="Requests" width="90" /> ``` ## Why this default [#why-this-default] The 60-second window is the default because liveness questions are about the last minute. The `now` clock is a required-in-spirit prop: the static entry must never call `Date.now()` (a server render and the client hydrate would disagree and mismatch), so you pass the clock from your data layer. Flatline is never dressed up — down and no-data are different states, and the summary distinguishes them. The boundary with `BreathingDot`: discrete arriving events are a HeartbeatBlip; a continuous level is a BreathingDot. ## Accessibility [#accessibility] The accessible name is the count, the window, and the time since the last event — **"3 events in the last minute; last 3s ago."** — or **"No events in the last minute."** when the trace is flat. The trace sweeps only when motion is allowed and on-screen; the live region announces on data change, and there is no per-spike navigation because the spikes are transient — the summary is the record. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `events` (required) | `number[]` | Event timestamps (ms). | | `window` | `number` | The visible recent window in ms (default 60000). | | `now` | `number` | Explicit clock — defaults to the latest event (SSR-safe). | | `label` | `"count" \| "none"` | Event-count numeral at the right. | 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](/docs/quickstart#the-shared-grammar). # HeatCell (/docs/charts/heat-cell) HeatCell answers "how intense is this one value against a known scale?". It is the single-cell building block for grids you lay out yourself — a matrix of tenants × hours, a custom calendar, a density chip in a sentence. Color is quantized into discrete steps: continuous opacity would fake precision a 12-px cell can't deliver. ```tsx <span className="inline-flex items-center gap-1.5"> {[12, 35, 58, 79, 96].map((v) => ( <HeatCell key={v} value={v} domain={[0, 100]} title={`Load ${v}`} style={{ width: 18, height: 18 }} /> ))} </span> ``` ## Install [#install] ```tsx import { HeatCell } from "@microcharts/react/heat-cell"; <HeatCell value={42} domain={[0, 100]} title="Load" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — table-cell matrices, custom grids, intensity chips beside labels. * **Avoid for** — precise comparison (MiniBar, DotPlot) or time series (HeatStrip, ActivityGrid). ## The shared-domain rule [#the-shared-domain-rule] A lone cell has no data to auto-scale from, so `domain` defaults to `[0, 1]` — pass your grid's real scale. **Every cell in one grid must share one domain**: per-cell auto-scaling would make the brightest hour of a quiet tenant look like the brightest hour of a loud one. ```tsx // one domain, computed once, shared by every cell const domain: [number, number] = [0, Math.max(...allValues)]; rows.map((r) => r.hours.map((v) => <HeatCell value={v} domain={domain} />)); ``` ## Variants [#variants] ```tsx <HeatCell value={70} domain={[0, 100]} shape="round" /> <HeatCell value={70} domain={[0, 100]} shape="dot" />`" > <span className="inline-flex items-center gap-1.5"> <HeatCell value="70" domain="[0, 100]" title="Square" style="{ width: 18, height: 18 }" /> <HeatCell value="70" domain="[0, 100]" shape="round" title="Round" style="{ width: 18, height: 18 }" /> <HeatCell value="70" domain="[0, 100]" shape="dot" title="Dot" style="{ width: 18, height: 18 }" /> </span> ``` ```tsx `"> <HeatCell value="8" domain="[0, 9]" label="value" title="Intensity" style="{ width: 28, height: 28 }" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <HeatCell value="Number.NaN" domain="[0, 100]" title="No data" style="{ width: 18, height: 18 }" /> ``` ```tsx <HeatCell value={140} domain={[0, 100]} />`" > <span className="inline-flex items-center gap-1.5"> <HeatCell value="-20" domain="[0, 100]" title="Below floor" style="{ width: 18, height: 18 }" /> <HeatCell value="140" domain="[0, 100]" title="Above ceiling" style="{ width: 18, height: 18 }" /> </span> ``` ## Why this default [#why-this-default] Five steps is the most a reader reliably distinguishes at cell size — the same ramp ActivityGrid uses, so intensity means one thing across the library. Values outside the domain clamp to the end steps (documented, never silently rescaled), and a zero-width domain renders the single mid step with a dev warning. ## Accessibility [#accessibility] The accessible name carries the value *and* its calibration — the shape cells above read **"70 — level 4 of 5."** — so the color scale is never the only channel. Non-finite input renders a designed empty track and says **"No data."** The interactive entry reveals the same reading on hover/focus, with ActivityGrid announcement parity. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The value to calibrate. | | `domain` | `[number, number]` | Calibration scale — defaults to [0, 1]; every cell in a grid must share one. | | `steps` | `number` | Discrete perceptual steps (default 5, shared with ActivityGrid). | | `shape` | `"square" \| "round" \| "dot"` | Shared cell vocabulary. | | `label` | `"value" \| "none"` | Centered number when the cell doubles as a chip. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # HeatStrip (/docs/charts/heat-strip) HeatStrip answers "how did intensity evolve, glanceably?". It is the 1×N sibling of ActivityGrid: the same discrete step scale, the same cell vocabulary, laid on a single timeline. Empty is not zero — a slot with no record renders a hairline outline, visibly different from a low value. ```tsx <HeatStrip data="[12, 25, 38, 52, 66, 79, 88, 90, 84, 71, 55, 40, 28, 45, 62, 78, 85, 74, 58, 35]" domain="[0, 100]" title="Load per hour" width="240" height="20" /> ``` ## Install [#install] ```tsx import { HeatStrip } from "@microcharts/react/heat-strip"; <HeatStrip data={hourlyLoad} domain={[0, 100]} title="Load per hour" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — per-tenant load rows, intensity ribbons in dense tables. * **Avoid for** — exact shape (Sparkline) or weekday rhythm (ActivityGrid). ## Variants [#variants] ```tsx <HeatStrip data={load} domain={[0, 100]} shape="dot" />`" > <span className="inline-flex flex-col gap-1.5"> <HeatStrip data="[12, 38, 66, 88, 84, 55, 28, 62, 85, 58]" domain="[0, 100]" shape="round" title="Round" width="160" height="14" /> <HeatStrip data="[12, 38, 66, 88, 84, 55, 28, 62, 85, 58]" domain="[0, 100]" shape="dot" title="Dot" width="160" height="14" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <HeatStrip data="[3, null, 8, null, 5]" title="Gaps" width="100" height="16" /> ``` ## Why this default [#why-this-default] Square cells with a density-adaptive gap keep boundaries legible where round shapes blur at 10 px. Every real value renders at a visible opacity (0.25–1); the faint track look is reserved for truly-empty slots. Three ways a heat strip lies — continuous ramps, per-row autoscale, mean-based downsampling — are all closed: discrete steps, shared `domain`, max-per-bucket only. ## Accessibility [#accessibility] The summary reuses `describeSeries` verbatim — for the load strip above that's **"Trending up 383%. Range 12 to 88. Last value 58."** — so a color ramp is never the only channel. The interactive entry roves cells with ActivityGrid-parity announcements (**"Point 8 of 20: 90."**, empty slots as "no data"). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | Time-ordered values; null = no record (≠ zero). | | `steps` | `number` | Shared step-scale granularity (default 5). | | `shape` | `"square" \| "round" \| "dot"` | Shared cell vocabulary. | | `domain` | `[number, number]` | Cross-row calibration — share one domain per table. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # HistogramStrip (/docs/charts/histogram-strip) HistogramStrip answers "what does the distribution look like?". Raw observations in, ≤ 12 uniform bins out — counts zero-anchored, never density-smoothed. Pre-aggregated counts are not supported; that's SparkBar's contract. ```tsx <HistogramStrip data="Array.from({ length: 120 }, (_, i) => (i % 3 === 0 ? 40 + (i % 10) : 20 + ((i * 7) % 60)))" title="Response times" style="{ width: 220, height: 56 }" /> ``` ## Install [#install] ```tsx import { HistogramStrip } from "@microcharts/react/histogram-strip"; <HistogramStrip data={times} title="Response times" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — latency clusters in a sentence, distributions per table row. * **Avoid for** — raw marks (RugStrip) or series over time (Sparkline). ## Variants [#variants] ```tsx i % 3 === 0 ? 40 + (i % 10) : 20 + ((i * 7) % 60), ); <HistogramStrip data={responseTimes} markValue={45} title="You are here" />`" > <HistogramStrip data="Array.from({ length: 120 }, (_, i) => i % 3 === 0 ? 40 + (i % 10) : 20 + ((i * 7) % 60), )" markValue="45" title="You are here" style="{ width: 220, height: 56 }" /> ``` ```tsx `" > <HistogramStrip data="[12000, 18000, 24000, 30000, 36000, 42000, 18000, 24000, 30000]" locale="de-DE" title="Localized bin edges" style="{ width: 220, height: 56 }" /> ``` The accessible summary states the modal bin's edges through `format`/`locale` — under `de-DE` a value like 24000 reads "24.000" (period as the thousands separator) instead of the English "24,000". ## Edge cases [#edge-cases] ```tsx `"> <HistogramStrip data="[]" title="No observations yet" style="{ width: 160, height: 40 }" /> ``` ```tsx `"> <HistogramStrip data="[4, 4, 4, 4, 4]" title="Constant" style="{ width: 160, height: 40 }" /> ``` An empty series renders zero bars and an accessible name of "No data." rather than a misleading flat line. A constant series collapses to ONE full-height bin instead of the usual up-to-12 slivers a naive equal-width binner would draw for a zero-span domain. ## Why this default [#why-this-default] Auto bin count is √n capped at 12 — enough shape to see skew, few enough bars to survive 60 px. All values identical collapse to ONE bin (never twelve slivers); explicit bin counts collapse to the observation count. `markValue` marks the bin of a value and never re-bins around it. ## Accessibility [#accessibility] The accessible name names the modal bin — **"120 values, most between 42.09 and 47.36."** The interactive entry roves bins with range announcements (**"42.09 to 47.36: 26 values."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Raw observations. | | `bins` | `number` | Bin count; auto = min(12, √n). | | `markValue` | `number` | A VALUE whose bin gets accent. | | `domain` | `[number, number]` | Fixed bin edges across multiples. | | `format` | `Intl.NumberFormatOptions \| fn` | Formats the bin edges named in the summary. | | `locale` | `string \| string[]` | BCP 47 locale(s) for the formatted bin edges. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Honeycomb (/docs/charts/honeycomb) Honeycomb answers "how many of the available slots are taken?" as filled cells in an area-filling hex grid. The unit is the cell, so the count is genuinely countable — this is occupancy of a capacity, not a magnitude. It fills row-major from the top-left, so occupancy reads as a sweep, and the whole grid is exactly two SVG paths (filled and empty) no matter how large the total. ```tsx <Honeycomb value="34" total="40" unit="seats" title="Occupancy" cell="6" /> ``` ## Install [#install] ```tsx import { Honeycomb } from "@microcharts/react/honeycomb"; <Honeycomb value={34} total={40} unit="seats" title="Occupancy" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — seats or licenses taken of a capacity, an occupancy read in a KPI card, or a countable of-total in a cell. * **Avoid for** — a capacity over about sixty (that's `Progress`), a magnitude with no total (MiniBar), or trends. ## Variants [#variants] ```tsx <Honeycomb value={28} total={40} empty="blank" />`" > <span className="inline-flex gap-6 items-center"> <Honeycomb value="7" total="10" rows="1" cell="6" /> <Honeycomb value="28" total="40" empty="blank" cell="5" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <Honeycomb value="0" total="12" unit="seats" title="Empty" cell="6" /> ``` ```tsx `"> <Honeycomb value="45" total="40" unit="seats" title="Overbooked" cell="6" /> ``` ```tsx `"> <Honeycomb value="0" total="0" title="No capacity" cell="6" /> ``` ## Why this default [#why-this-default] Outline empties are the default because takenness must survive grayscale — a filled cell versus an outlined cell reads without color. `empty="blank"` drops the empty cells entirely instead of dimming them, for surfaces where the outline reads as noise. Auto packing is the default because a near-square honeycomb is the recognizable form. The unit is the cell, and its size never changes with value — the count varies, the geometry doesn't — which is what keeps this honest area-filling *occupancy*, distinct from a `PictogramRow` counting unlike things. Above sixty cells, unit counting stops being countable, so the chart emits a dev warning and the docs steer to `Progress`. A value past the total fills every cell, but the accessible name still states the true number — occupancy is never silently clipped. ## Accessibility [#accessibility] The accessible name is the exact occupancy — **"45 of 40 seats filled."** — always the true value, even when it exceeds the total. The interactive entry announces the count on change through a polite live region and reveals the value / total on hover. Focus it and the arrow keys rove cell by cell (←/→ within a row, ↑/↓ holding the column), each cell announced as **"Cell 7 of 40 — filled."** The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | Filled count (fractional rounds). | | `total` | `number` | Capacity = cell count (default 10). | | `rows` | `number \| "auto"` | auto (near-square) or a number; 1 = strip. | | `empty` | `"outline" \| "blank"` | How empty cells render (default outline). | | `unit` | `string` | Noun for the summary (e.g. "seats"). | | `label` | `"none" \| "count" \| "percent"` | Centered readout when the comb has room (default "none"). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Horizon (/docs/charts/horizon) Horizon answers "what happened across this wide-range series — in a 14-pixel row?" The series is cut into bands and folded: layer opacity carries magnitude, so extremes stay visible at heights where a sparkline would flatten into noise. **How to read it** — every band rises from the row's bottom edge, positive or negative; darker means farther from the baseline, not which direction. Above-baseline values shade in the accent color, below-baseline in the negative color, so direction is never color-alone even though both fold upward the same way. ```tsx <Horizon data="[2, 5, 9, 14, 22, 31, 26, 18, 12, 24, 38, 45, 41, 30, 19, 11, 6, 3, 8, 16, 27, 35, 29, 20]" title="Cluster load" width="220" height="22" /> ``` ## Install [#install] ```tsx import { Horizon } from "@microcharts/react/horizon"; <Horizon data={cpuLoad} title="Cluster load" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — dense monitoring rows (dozens stacked), wide-range series in tight cells. * **Avoid for** — first-glance audiences (folding needs a key), or a few rows with room (Sparkline). ## Variants [#variants] ```tsx `" > <Horizon data="[2, 5, 9, 14, 22, 31, 26, 18, 12, 24, 38, 45, 41, 30, 19, 11, 6, 3, 8, 16, 27, 35, 29, 20]" folds="3" title="Three folds" width="220" height="22" /> ``` ```tsx `" > <Horizon data="[18, 22, 19, 25, 31, 20, 17, 24, 29, 21, 19, 26]" baseline="20" title="Latency vs 20 ms SLA" width="220" height="22" /> ``` ```tsx `" > <Horizon data="[ 200, 500, 900, 1400, 2200, 3100, 2600, 1800, 1200, 2400, 3800, 4500, ]" format="{ maximumFractionDigits: 0 }" locale="de-DE" title="Localized cluster load" width="220" height="22" /> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, the accessible summary's range and last-value numbers follow that locale's own grouping ("4.500" in German, not "4,500"). The interactive readout's per-point values localize the same way; the folded geometry never changes. ## Edge cases [#edge-cases] ```tsx `" > <Horizon data="[5, -3, 8, -12, 2, -6, 10]" title="Net flow" width="160" height="22" /> ``` ```tsx `"> <Horizon data="[5, 5, 5, 5, 5]" title="Flat" width="160" height="22" /> ``` Negative values take the negative token and fold from the same bottom edge as positive values (the default `mode="mirror"`) — both directions get darker as they move away from the baseline, so "denser" always means "farther from typical," never "which sign." Identical values across the whole row still render as a solid block rather than vanishing, keeping "flat" visibly distinct from "no data." ## Why this default [#why-this-default] Two folds is the default because it needs no training to read approximately; three folds trade learnability for density and should be reserved for ranges that genuinely span them. The `baseline` is authored, never inferred — a fold origin is a claim about what "normal" means. ## Accessibility [#accessibility] The accessible name reads the unfolded series — **"Trending up 900%. Range 2 to 45. Last value 20."** — so screen-reader users get the true values, not the folded geometry. The interactive readout announces unfolded values per point. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | Series over time. | | `folds` | `2 \| 3` | Band count — 3 only when the range genuinely spans it. | | `mode` | `"mirror" \| "offset"` | Mirror flips negatives upward (denser); offset keeps up/down. | | `baseline` | `number` | Fold origin (e.g. a target level) — authored, never inferred. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Hourglass (/docs/charts/hourglass) Hourglass answers "how much time is gone *and* how much remains?" — the two-sided story a progress bar can't tell. Sand fills the top chamber (remaining) and the bottom (elapsed), and both areas are **area-true**: a naive linear-height fill in a triangular bulb would overstate early progress by up to 2×, so the geometry solves for true proportional area. A thin stream at the neck marks "running"; it disappears at both ends, because finished and not-started are shape-distinct states. ```tsx <span className="inline-flex gap-4 items-center"> <Hourglass value="0.15" height="40" title="15% elapsed" /> <Hourglass value="0.5" height="40" title="half" /> <Hourglass value="0.85" height="40" title="85% elapsed" /> </span> ``` ## Install [#install] ```tsx import { Hourglass } from "@microcharts/react/hourglass"; <Hourglass value={0.75} title="Session" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a deadline or session-expiry read in a sentence, a TTL cell where remaining is the story, or a time-boxed tab or countdown. * **Avoid for** — exact percentages (Progress), trends (Sparkline), or non-time fractions. ## Variants [#variants] ```tsx <Hourglass value={1} />`" > <span className="inline-flex gap-6 items-center"> <Hourglass value="0.7" label="remaining" height="44" /> <Hourglass value="1" height="44" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <Hourglass value="0" title="Not started" height="36" /> ``` ```tsx `"> <Hourglass value="1" title="Finished" height="36" /> ``` ```tsx `" > <Hourglass value="1.4" title="Overrun" height="36" /> ``` ```tsx `"> <Hourglass value="Number.NaN" title="Invalid" height="36" /> ``` ## Why this default [#why-this-default] `value` is the elapsed fraction — the same polarity as `Progress` — so the two compose in one product without re-learning which way is which. The area-true solve is the load-bearing honesty rule: in an inherently nonlinear container, the sand areas are exactly proportional to elapsed and remaining. The stream is a binary state mark, not decoration, and is never animated in the static entry — it simply renders while `0 < value < 1`. ## Accessibility [#accessibility] The accessible name carries both sides — a glyph above reads **"70% elapsed, 30% remaining."** The interactive entry cross-fades the sand levels on change (opacity plus a scale-from-the-floor settle, never a path interpolation) and announces only when the value crosses a documented threshold (50 / 90 / 100%), so a streaming value never spams. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | Elapsed fraction 0–1 (like Progress). | | `stream` | `boolean` | The running-sand cue (default true). | | `label` | `"none" \| "remaining" \| "elapsed"` | Print the percent that matters to the context. | 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](/docs/quickstart#the-shared-grammar). # Hypnogram (/docs/charts/hypnogram) Hypnogram answers "which discrete state was the system in over time, and how choppy were the transitions?". It refuses interpolation — there are no diagonals, ever — because a state is a fact that holds until the next one, not a sample of a continuum a line chart can slope between. ```tsx `" > <Hypnogram data="[ { t: 0, state: "Awake" }, { t: 8, state: "Light" }, { t: 22, state: "Deep" }, { t: 38, state: "Light" }, { t: 50, state: "REM" }, { t: 62, state: "Light" }, { t: 74, state: "Deep" }, { t: 86, state: "Light" }, { t: 98, state: "REM" }, { t: 110, state: "Awake" }, ]" states="["Awake", "REM", "Light", "Deep"]" domain="[0, 120]" title="Sleep stages" width="300" height="64" /> ``` ## Install [#install] ```tsx import { Hypnogram } from "@microcharts/react/hypnogram"; <Hypnogram data={sleep} states={["Awake","REM","Light","Deep"]} title="Sleep stages" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — sleep stages, deploy / machine / incident state over time. * **Avoid for** — continuous signals (Sparkline) or a single current state (StatusDot). ## Variants [#variants] ```tsx `" > <Hypnogram data="[ { t: 0, state: "Awake" }, { t: 30, state: "REM" }, { t: 60, state: "Deep" }, { t: 90, state: "Light" }, ]" states="["Awake", "REM", "Light", "Deep"]" domain="[0, 120]" mode="lanes" title="Lanes" width="260" height="64" /> ``` ```tsx `" > <Hypnogram data="[ { t: 0, state: "Awake" }, { t: 8, state: "Light" }, { t: 22, state: "Deep" }, { t: 38, state: "Light" }, { t: 74, state: "Deep" }, { t: 110, state: "Awake" }, ]" states="["Awake", "REM", "Light", "Deep"]" domain="[0, 120]" emphasis="Deep" title="Deep emphasised" width="260" height="64" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <Hypnogram data="[{ t: 0, state: "Deep" }]" domain="[0, 120]" title="Deep sleep throughout" width="220" height="40" /> ``` ```tsx `" > <Hypnogram data="[ { t: 0, state: "Awake" }, { t: 20, state: "Groggy" }, { t: 40, state: "Light" }, ]" states="["Awake", "Light", "Deep"]" title="Unlisted state appended" width="220" height="52" /> ``` A single entry holds its state across the whole domain — one flat run, and the summary names it directly — **"1 state, no transitions; Deep throughout."** — rather than describing a one-point chart. A state present in the data but missing from an explicit `states` order is never dropped: it's appended as its own row (with a dev-only console warning), so the strip always accounts for every state it's given. ## Why this default [#why-this-default] Right-angle steps with an explicit `states` order are the clinically proven read. Order is meaningful — for ordinal states (sleep depth, incident severity) pass it explicitly; for nominal states with no rank, use `mode="lanes"` so the vertical axis never implies one. Any smoothing or easing of the step corners would be a lie about the data, so the entrance is a left-to-right clip reveal of the finished trace — the steps themselves are never interpolated. ## Accessibility [#accessibility] The accessible name summarises the shape — **"3 transitions across 4 states; longest run Awake."** The interactive entry roves the runs; each announces its state and span (**"Light, from 8 to 22."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ t, state }[]` | State holds from t to the next entry. | | `states` | `string[]` | Row order top→bottom; ordinal semantics live here. | | `emphasis` | `string` | Accents one state — the decision read. | | `mode` | `"steps" \| "lanes"` | Lanes for nominal states with no rank. | | `connectors` | `boolean` | Vertical transition strokes (default true); off for ultra-dense strips. | | `labels` | `boolean` | Left-gutter state names (default: on when width ≥ 96). | | `colors` | `string[]` | Per-state lane colours (lanes mode), cycled; overrides --mc-cat-N. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # IconArray (/docs/charts/icon-array) IconArray answers "how likely is this, really?". A stated rate becomes countable: filled units in a fixed N-unit grid, with the denominator visible. Two moves kill denominator neglect — the ratio label and the fixed grid. Fill order is contiguous reading-order (scattered is harder to count), and there are **no partial-unit fills ever**: a sub-unit rate is flagged, never faked. ```tsx <IconArray value="0.15" total="20" title="Adverse events" width="140" height="30" /> ``` ## Install [#install] ```tsx import { IconArray } from "@microcharts/react/icon-array"; <IconArray value={0.15} total={20} title="Adverse events" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — risk in a sentence, uptake / adoption rates, lay-audience probabilities. * **Avoid for** — a trend (Sparkline) or a full distribution (QuantileDots). ## Variants [#variants] ```tsx <IconArray value={0.15} total={20} positive="down" />`" > <span className="inline-flex flex-col gap-2"> <IconArray value="0.1" total="10" title="1 in 10" width="130" height="28" /> <IconArray value="0.15" total="20" positive="down" title="Risk polarity" width="150" height="28" /> </span> ``` ```tsx <IconArray value={0.6} total={10} shape="round" /> <IconArray value={0.37} total={100} label="none" />`" > <span className="inline-flex flex-col gap-2"> <IconArray value="0.15" total="20" label="percent" title="Percent label" width="110" height="26" /> <IconArray value="0.6" total="10" shape="round" title="Round units" width="130" height="28" /> <IconArray value="0.37" total="100" label="none" title="100-unit grid" width="90" height="90" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <IconArray value="0" total="20" title="No adverse events" width="140" height="30" /> ``` ```tsx `" > <IconArray value="0.01" total="20" title="Rare event" width="140" height="30" /> ``` ```tsx `"> <IconArray value="1" total="20" title="All affected" width="140" height="30" /> ``` A rate of exactly 0 draws every unit hollow. A rate that is real but rounds to 0 whole units (`note: "sub"`) still shows a hollow grid but the summary says so explicitly — never a fractional unit standing in for "almost none." `value` is clamped to `[0, 1]` and non-finite input renders as 0, so a bad upstream number never breaks the grid. ## Why this default [#why-this-default] `total={20}` and `label="ratio"` are the default pairing because "3 in 20" reads faster and more honestly for a lay audience than "15%" — the denominator stays visible instead of being computed in the reader's head. Units fill in reading order from the top-left, never scattered: medical-risk-communication research finds scattered fills measurably harder to count at a glance, and counting is the whole point of this chart. There is no partial-unit fill — a 37% rate is never drawn as a unit that's 37% full, because a sub-pixel sliver of color is a precision claim this chart doesn't make. ## Accessibility [#accessibility] The accessible name states the count and the rate — **"3 in 20. About 15%."** — and degenerate rates say so plainly ("0 in 20", "20 in 20 — all."). The interactive entry roves the grid in reading order with the arrow keys (2-D, row-major) and announces each unit's state plus the running count: **"Unit 1 of 20 — filled. 3 of 20 filled."** The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The rate, 0–1. | | `total` | `10 \| 20 \| 100` | Denominator / grid size (default 20). | | `label` | `"ratio" \| "percent" \| "none"` | "3 in 20" (default) reads better than "15%" for lay audiences. | | `shape` | `"square" \| "round" \| "dot"` | Shared cell vocabulary (default square). | | `positive` | `"up" \| "down"` | Polarity — down (fewer is better) flips the fill to the risk tone. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # All charts (/docs/charts) One grammar runs through all of them: `data` alone always renders something correct, and a prop name means the same thing on every chart. So you don't pick by chart — you pick by the **decision** you need read at a glance. The chooser below is filed exactly that way: start from the question, land on the chart. - [Browse all charts](/charts) ## Static and interactive [#static-and-interactive] Nearly every chart ships two entries — a hook-free **static** default (server-component safe, zero client JavaScript) and an **interactive** twin from a `/interactive` subpath. WindBarb is the lone static-only exception. Every chart page lists the import paths it has; the [Quickstart](/docs/quickstart#add-interactivity) covers when to reach for which, and [Accessibility](/docs/accessibility#one-interaction-contract) documents the one interaction contract they all share. # LikertStrip (/docs/charts/likert-strip) LikertStrip answers "does the response lean agree or disagree — and how hard?" — the valence + balance read that SegmentedBar (unvalenced composition) cannot say. The center line is the question; everything else is the answer. ```tsx <LikertStrip data="[ { label: "Strongly disagree", value: 10 }, { label: "Disagree", value: 14 }, { label: "Neutral", value: 14 }, { label: "Agree", value: 34 }, { label: "Strongly agree", value: 28 }, ]" title="Q1 satisfaction" width="220" height="24" /> ``` ## Install [#install] ```tsx import { LikertStrip } from "@microcharts/react/likert-strip"; <LikertStrip data={[ { label: "Strongly disagree", value: 10 }, { label: "Disagree", value: 14 }, { label: "Neutral", value: 14 }, { label: "Agree", value: 34 }, { label: "Strongly agree", value: 28 }, ]} title="Q1 satisfaction" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — survey question rows (share one scale via SparkGroup), sentiment in cards. * **Avoid for** — more than 7 levels, or exact per-level values (MiniBar). ## Variants [#variants] ```tsx <LikertStrip data={responses} label="net" />`" > <span className="inline-flex flex-col gap-3"> <LikertStrip data="[ { label: "Strongly disagree", value: 10 }, { label: "Disagree", value: 14 }, { label: "Neutral", value: 14 }, { label: "Agree", value: 34 }, { label: "Strongly agree", value: 28 }, ]" neutral="omit" title="Omit neutral" width="220" height="24" /> <LikertStrip data="[ { label: "Strongly disagree", value: 10 }, { label: "Disagree", value: 14 }, { label: "Neutral", value: 14 }, { label: "Agree", value: 34 }, { label: "Strongly agree", value: 28 }, ]" label="net" title="Net score" width="220" height="24" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <LikertStrip data="[ { label: "Disagree", value: 0 }, { label: "Agree", value: 0 }, ]" title="No responses" width="160" height="20" /> ``` ```tsx `" > <LikertStrip data="[ { label: "Disagree", value: 0 }, { label: "Neutral", value: 10 }, { label: "Agree", value: 0 }, ]" title="All neutral" width="160" height="20" /> ``` Empty data, or data whose values all resolve to 0, has nothing to divide into a diverging read — no bar draws, and the accessible name says so plainly: **"No responses."** When every non-zero response lands on the neutral level, the bar is entirely the center segment and the summary reads **"All responses neutral."** instead of forcing a lean out of no signal. Negative counts are treated as 0 rather than pushed the wrong direction across the center line — a chart that lies about which side a count is on is worse than one that drops it — and the static entry logs a dev warning when it happens. ## Why this default [#why-this-default] Both neutral conventions are supported honestly: `split` straddles the center (the canonical placement), `omit` removes neutral from the bar for cleaner pole comparison — but its share is ALWAYS still counted in the total and spoken in the accessible summary; neutral is never silently dropped. Graded opacity encodes ordinal distance from neutral, never magnitude. ## Accessibility [#accessibility] The accessible name is the full valence read — **"62% agree, 24% disagree, 14% neutral. Leans positive."** A |net| under 5 points reads "Balanced." The interactive entry steps levels in data order (**"Disagree: 14%, level 2 of 5."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value }[]` | Ordinal levels, negative → positive. | | `neutral` | `"split" \| "omit"` | Center-straddle or omit-from-bar (always labeled). | | `label` | `"ends" \| "net" \| "none"` | Agree/disagree % or one signed score. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # MicroBox (/docs/charts/micro-box) MicroBox answers "what are the p50 and spread of this metric?" — the five-number summary in a table row. Min-max whiskers by default (Tukey fences imply a normality assumption most product data doesn't meet); `tukey` mode exposes fence-breakers as dots. ```tsx <MicroBox stats="{ min: 12, q1: 35, median: 42, q3: 51, max: 96 }" title="p95 latency" width="220" height="32" /> ``` ## Install [#install] ```tsx import { MicroBox } from "@microcharts/react/micro-box"; <MicroBox stats={{ min: 12, q1: 35, median: 42, q3: 51, max: 96 }} title="p95 latency" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — latency percentile rows (p50/p95/p99), spread beside a stat — precomputed `stats` is the production path. * **Avoid for** — distribution shape (HistogramStrip) or fewer than 5 observations (renders honest dots). ## Variants [#variants] ```tsx 40 + i), 400, 500]; <MicroBox data={values} whiskers="tukey" />`" > <MicroBox data="[...Array.from({ length: 20 }, (_, i) => 40 + i), 400, 500]" whiskers="tukey" title="With outliers" style="{ width: 220, height: 32 }" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <MicroBox data="[3, 7, 9]" title="Only three" width="220" height="32" /> ``` ```tsx `" > <MicroBox data="[7, 7, 7, 7, 7, 7]" title="All equal" width="220" height="32" /> ``` ## Why this default [#why-this-default] Never a box from fewer than 5 observations — dots at the raw values instead. Precomputed `stats` with non-monotonic values are refused with a dev warning: garbage in must not render a plausible-looking lie. Outlier dots cap at 3 per side (the furthest). ## Accessibility [#accessibility] The accessible name is the five-number reading — **"Median 50.5, middle half 45.25 to 55.75, range 40 to 500."** The interactive entry roves a fixed 5-stop model (min → Q1 → median → Q3 → max), announcing each stat (**"Median: 42."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` | `number[]` | Raw observations (exclusive with stats). | | `stats` | `{ min; q1; median; q3; max }` | Precomputed server aggregates. | | `whiskers` | `"minmax" \| "tukey"` | Tukey exposes outliers as dots. | | `outliers` | `boolean` | Render outlier dots in tukey mode. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # MicroDonut (/docs/charts/micro-donut) MicroDonut answers "roughly what is this made of?" at icon size — an honest, capped concession to a ubiquitous demand. For any comparative read, use [SegmentedBar](/docs/charts/segmented-bar): a flat bar beats a donut of the same data at every size we ship. The wedge cap and labeled rollup are non-optional. ```tsx <MicroDonut data="[ { label: "Chrome", value: 620 }, { label: "Safari", value: 240 }, { label: "Firefox", value: 90 }, { label: "Edge", value: 30 }, { label: "Arc", value: 20 }, ]" size="48" title="Traffic mix" style="{ width: 72, height: 72 }" /> ``` ## Install [#install] ```tsx import { MicroDonut } from "@microcharts/react/micro-donut"; <MicroDonut data={mix} title="Traffic mix" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a mix icon beside the printed headline number in a KPI card. * **Avoid for** — any comparative read (SegmentedBar) — the docs steer there first. ## Variants [#variants] ```tsx 62% Chrome <MicroDonut data={mix} decorative /></span>`" > <span className="text-lg"> {"62% Chrome "} <MicroDonut data="[ { label: "Chrome", value: 620 }, { label: "Safari", value: 240 }, { label: "Firefox", value: 140 }, ]" style="{ width: "1em", height: "1em" }" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <MicroDonut data="[{ label: "Chrome", value: 620 }]" title="All Chrome" size="40" style="{ width: 40, height: 40 }" /> ``` ```tsx `"> <MicroDonut data="[]" title="Empty" size="40" style="{ width: 40, height: 40 }" /> ``` ## Why this default [#why-this-default] The hole is mandatory — the donut's angle + arc-length double encoding beats the pie's area read, which is why pie stays unshipped. Never exploded, tilted, or shadowed. A single category renders a full annulus that looks like a 100% ProgressRing — the summary disambiguates. ## Accessibility [#accessibility] The accessible name is the full composition (same wording as SegmentedBar). `decorative` marks the chart aria-hidden for the one sanctioned ornamental use — beside a printed value — and the interactive entry refuses to make a decorative donut a tab stop. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value }[]` | Parts of the whole. | | `maxWedges` | `number` | Rollup threshold (default 4). | | `decorative` | `boolean` | Redundant ornament beside a printed value → aria-hidden. | | `weight` | `number` | Annulus thickness (shared with ProgressRing). | | `label` | `"none" \| "total"` | Center total when the hole has room (default "none"). | | `colors` | `string[]` | Per-wedge colours, cycled; overrides --mc-cat-N. Other stays neutral. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # MicroScatter (/docs/charts/micro-scatter) MicroScatter answers "are these two variables related?" — the relationship story no other micro chart tells. Dots render at 75% opacity so overplot reads as density instead of lying by occlusion, and duplicates are never jittered: position is the encoding. ```tsx <span className="text-lg"> {"Latency and error rate "} <MicroScatter data="Array.from({ length: 24 }, (_, i) => ({ x: i, y: i * 3 + ((i * 7) % 5) * 6 }))" title="Latency vs error rate" style="{ width: "3em", height: "1.8em" }" /> {" correlate strongly."} </span> ``` ## Install [#install] ```tsx import { MicroScatter } from "@microcharts/react/micro-scatter"; <MicroScatter data={pairs} title="Latency vs error rate" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — correlation in a sentence, two-metric relationships in KPI cards. * **Avoid for** — more than 60 points (bin instead) or ordered time series (Sparkline). ## Variants [#variants] ```tsx `" > <MicroScatter data="Array.from({ length: 24 }, (_, i) => ({ x: i, y: i * 3 + ((i * 7) % 5) * 6 }))" title="With trend" style="{ width: 140, height: 84 }" /> ``` ```tsx `"> <MicroScatter data="Array.from({ length: 24 }, (_, i) => ({ x: i, y: i * 3 + ((i * 7) % 5) * 6 }))" focal="12" title="You are here" style="{ width: 140, height: 84 }" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <MicroScatter data="[]" title="No pairs" style="{ width: 100, height: 60 }" /> ``` ```tsx `"> <MicroScatter data="[ { x: 1, y: 2 }, { x: 2, y: 3 }, ]" title="Two points" style="{ width: 100, height: 60 }" /> ``` ```tsx `"> <MicroScatter data="[ { x: 5, y: 5 }, { x: 5, y: 5 }, { x: 1, y: 8 }, ]" title="Overlapping pair" style="{ width: 100, height: 60 }" /> ``` Empty data draws just the frame with "No data." as the summary. Under 3 points (or a zero-variance cloud) states the count and stops — no correlation claim without enough evidence to back it. Coincident points are never jittered apart: they overlap exactly, and at 75% dot opacity the overlap itself reads as extra density rather than hiding a point. ## Why this default [#why-this-default] Axes are unlabeled at this scale, so `title` must name both variables, the way the hero demo above does. The summary's relationship words are a documented heuristic on |r| (≥ 0.7 strong, ≥ 0.4 moderate, ≥ 0.2 weak), and whenever a relationship word appears, r appears beside it: claim and evidence travel together. Fewer than 3 points, or a zero-variance cloud, makes no claim at all. ## Accessibility [#accessibility] The accessible name is the count plus the evidence-backed relationship — **"24 points. Strong positive relationship (r 0.93)."** — or just **"2 points."** when no claim is honest. The interactive entry steps points ordered by x and announces each formatted pair. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ x; y }[]` | Unordered pairs. | | `trend` | `boolean` | Least-squares line — linear only, never smoothed. | | `focal` | `number` | Accent one point — "this one, among all of them". | | `xDomain` | `[number, number]` | X scale (domain keeps its grammar meaning: y). | | `domain` | `[number, number]` | Y scale — the shared grammar name, paired with xDomain. | | `r` | `number` | Dot radius, clamped [1, 3]. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # MiniBar (/docs/charts/mini-bar) MiniBar answers "which category is biggest, and by roughly how much?". Bars are always zero-anchored, and the data's own order is the default truth — weekday order or funnel order carries meaning that ranking would destroy, so `order` is explicit, never silent. ```tsx <MiniBar data="[ { label: "East", value: 940 }, { label: "West", value: 410 }, { label: "South", value: 620 }, { label: "North", value: 120 }, ]" title="Sales by region" width="150" height="48" /> ``` ## Install [#install] ```tsx import { MiniBar } from "@microcharts/react/mini-bar"; <MiniBar data={regions} title="Sales by region" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — per-row category mix in tables, small comparisons in KPI cards. * **Avoid for** — more than 8 categories (a full bar chart) or time series (SparkBar). ## Variants [#variants] ```tsx <MiniBar data={regions} highlight="South" />`" > <span className="inline-flex gap-6"> <MiniBar data="[ { label: "East", value: 940 }, { label: "West", value: 410 }, { label: "South", value: 620 }, { label: "North", value: 120 }, ]" order="desc" title="Ranked" width="120" height="36" /> <MiniBar data="[ { label: "East", value: 940 }, { label: "West", value: 410 }, { label: "South", value: 620 }, { label: "North", value: 120 }, ]" highlight="South" title="This row's category" width="120" height="36" /> </span> ``` ```tsx `" > <MiniBar data="[ { label: "Mon", value: 4 }, { label: "Tue", value: -2 }, { label: "Wed", value: 6 }, { label: "Thu", value: -1 }, { label: "Fri", value: 3 }, ]" positive="up" title="Daily delta" width="120" height="36" /> ``` ```tsx `" > <MiniBar data="[ { label: "East", value: 12400 }, { label: "West", value: 8600 }, ]" locale="de-DE" title="Localized values" width="80" height="36" /> ``` The extremes named in the summary follow `format`/`locale` — 12400 reads "12.400" under `de-DE` rather than the English "12,400". ## Edge cases [#edge-cases] ```tsx `" > <MiniBar data="[ { label: "a", value: 5 }, { label: "b", value: null }, { label: "c", value: 7 }, ]" title="Gap preserved" width="120" height="36" /> ``` ```tsx `"> <MiniBar data="[{ label: "Only", value: 4 }]" title="Single" width="80" height="36" /> ``` A `null` value draws no bar but keeps its band, so the two real bars around it stay exactly as far apart as a fully populated row — alignment across a column of MiniBars survives missing data. A single category still renders and its summary says so plainly ("1 category…") rather than degenerating into a bare-bar special case. Past 8 categories the component still renders every bar (nothing is dropped or truncated) but logs a dev warning — MiniBar is a cell chart, and a wider comparison belongs in a full bar chart. ## Why this default [#why-this-default] Unsorted by default: the data's order often IS information. Null values keep their slot as a gap, so a missing category never shifts its neighbors. Explicit domains are widened to include zero — a bar whose length doesn't start at zero is a lie, so the component refuses to draw one. ## Accessibility [#accessibility] The accessible name carries count and extremes — **"4 categories. Highest East 940, lowest North 120."** The interactive entry announces each bar with its rank: **"East: 940 — 1st of 4."** The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value }[]` | Categories in meaningful order. | | `order` | `"data" \| "desc" \| "asc"` | Ranking read vs positional read — data-facing, not styling. | | `highlight` | `number \| string` | Index or label to emphasize. | | `orientation` | `"horizontal" \| "vertical"` | Rows for wider, shorter cells. | | `positive` | `"up" \| "down"` | Engages pos/neg tokens on signed data. | | `label` | `"none" \| "max"` | Peak-value readout (vertical only; default "none"). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # MinimapStrip (/docs/charts/minimap-strip) MinimapStrip answers "where am I in the whole — and where in the whole is everything else I care about?". A content thumbnail sits under a viewport window and a lane of annotation ticks, and any region you haven't loaded or crawled is drawn as fog rather than blank — because absence is not the same as zero. The unknown share travels with the accessible name. ```tsx <MinimapStrip data="{ content: Array.from({ length: 1200 }, (_, i) => Math.abs(Math.sin(i / 40)) + Math.abs(Math.sin(i / 150)) * 0.6), window: [520, 660], marks: [100, 600, 1100], known: [[0, 1104]], }" title="Document position" width="300" height="18" /> ``` ## Install [#install] ```tsx import { MinimapStrip } from "@microcharts/react/minimap-strip"; <MinimapStrip data={{ content: Array.from( { length: 1200 }, (_, i) => Math.abs(Math.sin(i / 40)) + Math.abs(Math.sin(i / 150)) * 0.6, ), window: [520, 660], marks: [100, 600, 1100], known: [[0, 1104]], }} title="Document position" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — document or log position, long-timeline navigation. * **Avoid for** — a single value (Progress) or exact content values (Sparkline). ## Variants [#variants] ```tsx Math.abs(Math.sin(i / 40)) + Math.abs(Math.sin(i / 150)) * 0.6, ), window: [300, 440], marks: [600, 1000], }} mode="heat" />`" > <MinimapStrip data="{ content: Array.from({ length: 1200 }, (_, i) => Math.abs(Math.sin(i / 40)) + Math.abs(Math.sin(i / 150)) * 0.6), window: [300, 440], marks: [600, 1000], }" mode="heat" title="Heat" width="300" height="18" /> ``` ## Edge cases [#edge-cases] ```tsx Math.abs(Math.sin(i / 20))), window: [40, 90], known: [[0, 200]], }} />`" > <MinimapStrip data="{ content: Array.from({ length: 200 }, (_, i) => Math.abs(Math.sin(i / 20))), window: [40, 90], known: [[0, 200]], }" title="Fully known" width="220" height="16" /> ``` ## Why this default [#why-this-default] Bars plus a separate mark lane keep "where am I" and "where are the annotations" as two clean reads instead of one muddle. Fog-of-war is a first-class state — unknown regions get a hatched texture, never a blank stretch that would read as empty content, and the unknown share is disclosed in the summary. The window maps linearly to the domain; there is no fisheye to distort where you are. ## Accessibility [#accessibility] The accessible name places you in the whole — **"Viewing 12% of the whole (300–440 of 1,200); 2 marks."** The interactive entry is a slider: drag or click to move the window, or nudge it with ←/→ (Shift for a bigger jump). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ content, window, marks?, known? }` | Density series, viewport, ticks, covered regions. | | `mode` | `"bars" \| "heat"` | Heat is a calmer opacity strip. | | `markLane` | `boolean` | Dedicated tick lane vs overlaying ticks. | | `onWindowChange` | `(window: [number, number]) => void` | (interactive) Fires with the new `[start, end]` index range as the brush window is dragged. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # MoonPhase (/docs/charts/moon-phase) MoonPhase answers "how far through the cycle or period are we?" with a form almost everyone reads without a legend: the illuminated fraction of a disc. The lit **area** equals the value exactly — a closed-form terminator, not the phase-angle approximation that under-lights mid-cycle — so 50% genuinely lights half the disc. Progress mode fills monotonically; cycle mode maps the real lunar sequence. ```tsx <span className="inline-flex gap-3 items-center"> <MoonPhase value="0.1" size="24" title="10%" /> <MoonPhase value="0.35" size="24" title="35%" /> <MoonPhase value="0.5" size="24" title="50%" /> <MoonPhase value="0.75" size="24" title="75%" /> <MoonPhase value="1" size="24" title="full" /> </span> ``` ## Install [#install] ```tsx import { MoonPhase } from "@microcharts/react/moon-phase"; <MoonPhase value={0.68} title="Sprint" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — sprint or quota progress in a sentence, a billing-period or release-cycle marker, or any 0–1 completion that reads at a glance. * **Avoid for** — exact percentages (Progress), trends (Sparkline), or comparisons (MiniBar). ## Variants [#variants] ```tsx // first quarter <MoonPhase value={0.5} mode="cycle" /> // full moon`" > <span className="inline-flex gap-3 items-center"> <MoonPhase value="0" mode="cycle" size="24" title="new" /> <MoonPhase value="0.25" mode="cycle" size="24" title="first quarter" /> <MoonPhase value="0.5" mode="cycle" size="24" title="full" /> <MoonPhase value="0.75" mode="cycle" size="24" title="last quarter" /> </span> ``` ## Edge cases [#edge-cases] ```tsx // clamps to 0 — new, dark disc <MoonPhase value={1.6} title="Above one" /> // clamps to 1 — full, lit disc`" > <span className="inline-flex gap-3 items-center"> <MoonPhase value="-0.4" size="28" title="Below zero" /> <MoonPhase value="1.6" size="28" title="Above one" /> </span> ``` ## Why this default [#why-this-default] Progress mode is the default because period-progress is the common need — a sprint or quota filling from new to full, monotonically. Pretending the real lunar cycle is monotonic would lie (it waxes then wanes), so `mode="cycle"` is a separate, explicit data-semantic switch, not a preset. The lit area is always exactly the value via the closed form — never the phase-angle shortcut. Area is a medium-precision channel, so steer exact reads to `Progress`; MoonPhase is for the glance. ## Accessibility [#accessibility] The accessible name states the fraction — **"0% of the cycle complete."** in progress mode, or "0% through the cycle." in cycle mode. The interactive entry fades the lit region back in on change with a slight bloom (opacity plus a small scale, never a path interpolation, and skipped entirely under `prefers-reduced-motion`), reveals the exact percent on hover or focus, and announces changes through a polite live region throttled to at most once a second. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | Fraction 0–1 (clamped). | | `mode` | `"progress" \| "cycle"` | progress = monotonic fill; cycle = true lunar mapping (0 new → 0.5 full → 1 new). | 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](/docs/quickstart#the-shared-grammar). # MusicStaff (/docs/charts/music-staff) MusicStaff answers "what's the shape of this short series?" by reading it as a melody: each value is a note, its **pitch** (vertical position on a five-line staff) is the value, and left-to-right is time. Pitch is the only channel — there are no clefs, stems, beams, or bar lines, because every other notation convention would be decoration. The read is in steps (nine to thirteen positions), so exact values steer to `Sparkline` with a label. ```tsx `" > <MusicStaff data="[3, 5, 4, 8, 6, 9, 7, 11]" label="last" title="Sprint melody" width="120" height="26" /> ``` ## Install [#install] ```tsx import { MusicStaff } from "@microcharts/react/music-staff"; <MusicStaff data={weeks} title="Sprint melody" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a weekly-rhythm read in a sentence, the shape of a sprint or short series in a cell, or a per-channel melody in a tab. * **Avoid for** — exact values (Sparkline with a label), long series (over sixteen points), or trends where the exact slope matters. ## Variants [#variants] ```tsx <MusicStaff data={[3, 5, null, 8, 6]} />`" > <span className="inline-flex gap-6 items-center"> <MusicStaff data="[3, 5, 4, 8, 6, 9]" mode="staff" width="100" height="24" /> <MusicStaff data="[3, 5, null, 8, 6]" width="90" height="24" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <MusicStaff data="[7]" title="One value" width="60" height="24" /> ``` ```tsx `" > <MusicStaff data="[null, null, null]" title="No notes" width="80" height="24" /> ``` ```tsx `"> <MusicStaff data="[3000, 5200, 4100, 8300, 6400]" label="last" locale="de-DE" title="Localized last value" width="110" height="24" /> ``` A single value draws one note and no contour line — a melody needs at least two notes to have a shape. An all-`null` series draws the bare staff with no notes at all; the accessible name falls back to `describeSeries`'s own no-data phrasing. With a `locale`, the trailing `label="last"` value follows that locale's own grouping and decimal marks. ## Why this default [#why-this-default] The ledger mode is the default because clipping pitch silently is worse than two extra hairline ledger ticks — a note above or below the staff still reads truly. `mode="staff"` exists for dense cells where ledger lines would collide with a neighbour; there, out-of-range pitches clamp to the nearest staff line or space instead, trading visual precision for a collision-free cell — the accessible summary is unaffected either way, since it describes the raw values, not the clamped pixel positions. Two adjacent equal values are spaced by the time axis, never dodged vertically, because moving a note vertically would change its pitch — and pitch is the data. ## Accessibility [#accessibility] MusicStaff reuses the same natural-language summary as `Sparkline`, verbatim — for `[3, 5, 4, 8, 6, 9]`, **"Trending up 200%. Range 3 to 9. Last value 9."** The interactive entry steps the notes with ←/→, announcing each as **"Point 3 of 6: 4."** The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | The series; null = a rest. | | `mode` | `"staff" \| "ledger"` | ledger (±2, default) or staff (clamp on-staff). | | `label` | `"none" \| "last"` | Print the final value after the last note. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # NetFlow (/docs/charts/net-flow) NetFlow answers "in versus out — and where does that leave us net?". Inflow is an area above a zero baseline, outflow is mirrored below it on **one shared magnitude scale** (never independently scaled to balance the picture), and the net line (`in − out`) rides on top to restore the precise decision value. Gross and net answer different questions; the cell answers both. ```tsx <NetFlow data="[ { in: 42, out: 31 }, { in: 38, out: 35 }, { in: 45, out: 29 }, { in: 40, out: 44 }, { in: 52, out: 38 }, { in: 48, out: 41 }, { in: 55, out: 36 }, { in: 50, out: 47 }, { in: 58, out: 39 }, { in: 44, out: 52 }, { in: 60, out: 41 }, { in: 57, out: 43 }, ]" format="(n) => `${n}k`" label="last" title="Monthly cash flow" width="260" height="30" /> ``` ## Install [#install] ```tsx import { NetFlow } from "@microcharts/react/net-flow"; <NetFlow data={months} title="Monthly cash flow" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — cash flow per account row, in vs out (signups vs churn) in a KPI card, any in-vs-out where the net is the decision. * **Avoid for** — a single net series (Sparkline) or one period's split (Delta / SegmentedBar). ## Variants [#variants] ```tsx <NetFlow data={months} positive="down" />`" > <span className="inline-flex flex-col gap-1.5"> <NetFlow data="[ { in: 45, out: 29 }, { in: 40, out: 44 }, { in: 52, out: 38 }, { in: 44, out: 52 }, { in: 60, out: 41 }, { in: 57, out: 43 }, ]" mode="bars" title="Mirrored bars" width="220" height="28" /> <NetFlow data="[ { in: 45, out: 29 }, { in: 40, out: 44 }, { in: 52, out: 38 }, { in: 44, out: 52 }, { in: 60, out: 41 }, { in: 57, out: 43 }, ]" positive="down" title="Outflow is the goal" width="220" height="28" /> </span> ``` ```tsx `" > <NetFlow data="[ { in: 42000, out: 31000 }, { in: 38000, out: 35000 }, ]" locale="de-DE" title="Localized flow" width="140" height="26" /> ``` The net label and accessible summary both follow `format`/`locale` — 38000 reads "38.000" under `de-DE` rather than the English "38,000". ## Edge cases [#edge-cases] ```tsx `" > <NetFlow data="[{ in: 40, out: 25 }]" title="This month" width="140" height="28" /> ``` ```tsx `" > <NetFlow data="[{ in: -5, out: -3 }]" title="Bad reading" width="140" height="28" /> ``` A single period always renders as mirrored bars, never an area — an area drawn through one point would imply continuity the data doesn't have. `in`/`out` are magnitudes: a negative value is invalid input, not a reversed direction, so it's coerced to `0`. When every period's magnitudes are zero (all periods coerced or genuinely empty), NetFlow draws only the zero baseline — no areas, no bars, no net line — and the accessible name says so plainly: **"No flow across 1 period."** ## Why this default [#why-this-default] Mirrored areas plus a net line, because gross and net answer different questions and a cell must answer both. Both directions share **one** scale — never independently scaled to make the picture look balanced — and both areas anchor at zero, so their extents are honest. The net line is a plain `in − out`, never smoothed, and its sign is stated in the label's **text** so direction is never carried by color alone. ## Accessibility [#accessibility] The accessible name pairs the net with its gross and counts the healthy periods — **"Net +14 last period; in 57 vs out 43; net positive 4 of 6 periods."**. The interactive entry steps the periods and announces inflow, outflow, and the signed net together. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ in; out }[]` | Periods, oldest first — inflow and outflow magnitudes (both ≥ 0). | | `mode` | `"area" \| "bars"` | Mirrored areas (default) or discrete columns for few periods. | | `net` | `boolean` | The net line (in − out). Default true. | | `positive` | `"up" \| "down"` | Which direction is good — 'down' for debt-paydown contexts. | | `label` | `"last" \| "none"` | Signed net in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Ohlc (/docs/charts/ohlc) Ohlc answers "what was the price action per period?" — open, high, low, close, in a cell. Direction is encoded by valence color AND body geometry, never color alone. ```tsx `" > <Ohlc data="Array.from({ length: 20 }, (_, i) => { const base = 140 + Math.sin(i / 3) * 8 + i * 0.6; return { open: Math.round(base * 10) / 10, high: Math.round((base + 3 + (i % 3)) * 10) / 10, low: Math.round((base - 3 - (i % 2)) * 10) / 10, close: Math.round((base + (i % 2 === 0 ? 2 : -1.5)) * 10) / 10, }; })" title="ACME 20 sessions" width="240" height="30" /> ``` ## Install [#install] ```tsx import { Ohlc } from "@microcharts/react/ohlc"; <Ohlc data={sessions} title="ACME sessions" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — watchlist table rows, ticker KPI cards. * **Avoid for** — a single close series (Sparkline), or more than \~20 periods. ## Variants [#variants] ```tsx <Ohlc data={sessions} label="last" />`" > <span className="inline-flex flex-col gap-3"> <Ohlc data="Array.from({ length: 20 }, (_, i) => { const base = 140 + Math.sin(i / 3) * 8 + i * 0.6; return { open: Math.round(base * 10) / 10, high: Math.round((base + 3 + (i % 3)) * 10) / 10, low: Math.round((base - 3 - (i % 2)) * 10) / 10, close: Math.round((base + (i % 2 === 0 ? 2 : -1.5)) * 10) / 10, }; })" mode="bars" title="Bar form" width="240" height="30" /> <Ohlc data="Array.from({ length: 20 }, (_, i) => { const base = 140 + Math.sin(i / 3) * 8 + i * 0.6; return { open: Math.round(base * 10) / 10, high: Math.round((base + 3 + (i % 3)) * 10) / 10, low: Math.round((base - 3 - (i % 2)) * 10) / 10, close: Math.round((base + (i % 2 === 0 ? 2 : -1.5)) * 10) / 10, }; })" label="last" title="With last close" width="260" height="30" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <Ohlc data="[ { open: 100, high: 103, low: 98, close: 102 }, { open: 102, high: 104, low: 99, close: 102 }, { open: 102, high: 105, low: 100, close: 101 }, ]" title="Doji in the middle" width="120" height="26" /> ``` ```tsx `"> <Ohlc data="[{ open: 100, high: 104, low: 97, close: 103 }]" title="Single period" width="60" height="26" /> ``` ## Why this default [#why-this-default] `maxPeriods` renders the most recent N sessions and warns in development past it — data is truncated visibly, never averaged into fake candles. Bodies keep a minimum 1-unit height so doji sessions stay visible. ## Accessibility [#accessibility] The accessible name is the run read — **"20 periods. Last close 150.3, up 7.4%; range 136.4 to 156."** The interactive entry announces each session's four prices (**"Period 18 of 20: open 145.6, high 150.6, low 141.6, close 144.1."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ open; high; low; close }[]` | Periods, oldest first. | | `mode` | `"candle" \| "bars"` | Candle bodies or open/close ticks. | | `maxPeriods` | `number` | Renders the most recent N (never averaged). | | `label` | `"last" \| "none"` | Last close in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # OrbitStatus (/docs/charts/orbit-status) OrbitStatus answers "how slow and how busy is this dependency right now?" in one small mark. The orbit radius is latency — a wider orbit is a slower service — and the orbit's dash density is the call rate, denser dashes meaning more calls. In the interactive entry the satellite orbits at a speed that mirrors that rate, so a busy service visibly spins faster. Both channels are deliberately low-precision ambient reads; for exact numbers, use a `Sparkline` for latency and a `Delta` or `MiniBar` for rate. ```tsx <OrbitStatus latency="240" rate="12" latencyDomain="[0, 500]" rateDomain="[0, 20]" title="Payments API" size="40" /> ``` ## Install [#install] ```tsx import { OrbitStatus } from "@microcharts/react/orbit-status"; <OrbitStatus latency={240} rate={12} latencyDomain={[0, 500]} rateDomain={[0, 20]} title="Payments API" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## Motion, and reduced motion [#motion-and-reduced-motion] The satellite's angular speed is quantized to the same five steps as the static dash density, so the motion and the still frame decode identically — you learn nothing extra from watching, you just feel the rate. This is the deliberate idle-loop exception, allowed because the loop rate is the datum. It pauses off-screen and, under `prefers-reduced-motion`, does not spin at all: the dash density already carries the rate. The satellite's angular *position* never means anything — only its speed does — so the docs say plainly not to read the angle. ## When to use it [#when-to-use-it] * **Good for** — a live dependency health dot in a service table, latency and rate together in one small mark, or an infra status glance. * **Avoid for** — exact latency (`Sparkline`), exact rate (`Delta`, `MiniBar`), or a trend over time (`Sparkline`). ## Sizing [#sizing] One `size` prop, in viewBox units, sets the orbit box — it defaults to `20`. There is no separate `width`/`height`: the glyph is square, and the rendered box widens only by the gutter a `label` reserves. `fontSize` follows `size` unless you set it. ## Variants [#variants] ```tsx <OrbitStatus latency={100} rate={0} latencyDomain={[0, 500]} rateDomain={[0, 20]} />`" > <span className="inline-flex gap-6 items-center"> <OrbitStatus latency="340" rate="8" threshold="300" latencyDomain="[0, 500]" rateDomain="[0, 20]" size="40" summary="false" /> <OrbitStatus latency="100" rate="0" latencyDomain="[0, 500]" rateDomain="[0, 20]" size="40" summary="false" /> </span> ``` ```tsx `" > <OrbitStatus latency="1240" rate="12" latencyDomain="[0, 2000]" rateDomain="[0, 20]" label="latency" locale="de-DE" title="Localized latency" size="40" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <OrbitStatus latency="NaN" rate="5" title="Unreachable" size="40" /> ``` ```tsx `"> <OrbitStatus latency="90" rate="0" latencyDomain="[0, 500]" rateDomain="[0, 20]" size="40" /> ``` ## Why this default [#why-this-default] The dash-density static encoding exists because a paused satellite says nothing — the still frame had to carry both variables or the chart would fail the survivor test, so rate lives in the dashes as well as the spin. The rate is quantized to five ordinal steps in both renderings — five dash counts and five angular periods — and radius and speed always come from the same domains in the static and interactive frames, so nothing drifts. A lone orbit radius is meaningless, so the docs insist on explicit `latencyDomain` and `rateDomain` — the same steer as `FatDigits`. At `threshold`, the satellite doubles and flags the summary, never relying on color alone. Unknown latency or rate goes gray and stops the spin: an unknown dependency must not look healthy. ## Accessibility [#accessibility] The accessible name is both variables with units — **"240ms latency at 12 calls/s."** — plus "— above threshold" when the latency crosses `threshold`, or **"Latency unknown."** when a value is missing. The threshold state is carried by the satellite's size and the summary, never color alone; motion is gated on `prefers-reduced-motion`; and the live region announces threshold crossings only. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `latency` (required) | `number` | Orbit radius (weak — pass a domain). | | `rate` (required) | `number` | Dash density / satellite speed. | | `latencyDomain` | `[number, number]` | Latency extent (insist on it — a lone radius is meaningless). | | `rateDomain` | `[number, number]` | Rate extent (default [0, 2·rate]). | | `threshold` | `number` | Latency threshold: at/above it the satellite doubles + the summary flags it. | 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](/docs/quickstart#the-shared-grammar). # PairedBars (/docs/charts/paired-bars) PairedBars answers "how does actual compare to expected, category by category?". Value and reference always share one zero-anchored domain — comparing bars on different scales is the cardinal grouped-bar lie — and the reference is muted by two structural cues (opacity *and* width), never color alone. ```tsx `" > <PairedBars data="[ { label: "East", value: 940, ref: 1200 }, { label: "West", value: 410, ref: 400 }, { label: "South", value: 620, ref: 600 }, { label: "North", value: 120, ref: 300 }, ]" title="Actual vs plan" width="200" height="64" /> ``` ## Install [#install] ```tsx import { PairedBars } from "@microcharts/react/paired-bars"; <PairedBars data={regions} title="Actual vs plan" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — budget vs actual per region, target vs result rows. * **Avoid for** — data without a reference series (MiniBar) or more than 5 pairs. ## Variants [#variants] ```tsx `" > <PairedBars data="[ { label: "East", value: 940, ref: 1200 }, { label: "West", value: 410, ref: 400 }, ]" mode="overlay" title="Overlay" width="140" height="44" /> ``` ```tsx `" > <PairedBars data="[ { label: "East", value: 940, ref: 1200 }, { label: "West", value: 410, ref: 400 }, ]" positive="up" title="Over/under plan" width="140" height="44" /> ``` ```tsx `" > <PairedBars data="[{ label: "East", value: 9400, ref: 12000 }]" locale="de-DE" title="Localized" width="80" height="44" /> ``` The gap named in the summary follows `format`/`locale` — 12000 reads "12.000" under `de-DE` rather than the English "12,000". ## Edge cases [#edge-cases] ```tsx `" > <PairedBars data="[{ label: "East", value: 940, ref: null }]" title="No plan yet" width="100" height="44" /> ``` ```tsx `"> <PairedBars data="[{ label: "East", value: 940, ref: 1200 }]" title="Single pair" width="80" height="44" /> ``` A pair whose `ref` is `null` draws its value bar alone — no ghost, no zero-width placeholder — and the interactive entry announces it as **"East: 940, no reference."** rather than pretending a comparison exists. Past 5 pairs the grouped read blurs into noise, so the component still renders every pair but logs a dev warning. ## Why this default [#why-this-default] Grouped over overlay by default — overlap hides small over-shoots, so the denser overlay form is the variant you choose for tight cells, not the analytical default. A pair with a missing reference renders the value bar alone and announces "no reference"; a chart where *every* reference is missing dev-warns and steers to MiniBar. ## Accessibility [#accessibility] The accessible name leads with the largest gap — **"2 pairs. Largest gap East: 940 vs 1,200."** The interactive entry roves pairs and announces each as value vs reference (**"East: 940 vs 1,200."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value; ref }[]` | Value + reference per category. | | `mode` | `"grouped" \| "overlay"` | Overlay puts the ref as a full-width ghost behind — halves the footprint. | | `positive` | `"up" \| "down"` | Over/under-reference valence tint. | | `orientation` | `"horizontal" \| "vertical"` | Rows for wide cells. | | `locale` | `string \| string[]` | BCP 47 locale(s) for the gap named in the summary, e.g. "de-DE". | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # ParetoStrip (/docs/charts/pareto-strip) ParetoStrip answers "what should we fix first?". It sorts the categories descending and overlays a **cumulative-share line on a fixed 0–100% scale** that spans the full height and is never rescaled to steepen the curve. The bars up to the threshold crossing are accent — the **vital few** — and the rest are muted, because the chart's one job is to say where to stop reading. 80% is a working reference, not a law, and `Other` never re-enters the ranking. ```tsx <ParetoStrip data="[ { label: "Timeouts", value: 38 }, { label: "OOM", value: 24 }, { label: "Deploy", value: 15 }, { label: "Config", value: 9 }, { label: "Network", value: 7 }, { label: "Auth", value: 4 }, { label: "Disk", value: 3 }, { label: "DNS", value: 3 }, { label: "Other bug", value: 2 }, ]" unit="causes" metric="incidents" title="Incident causes" width="260" height="28" /> ``` ## Install [#install] ```tsx import { ParetoStrip } from "@microcharts/react/pareto-strip"; <ParetoStrip data={causes} unit="causes" metric="incidents" title="Incident causes" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a "fix these three" read in a KPI card, incident causes or support tags in a tab header, any long-tail composition where a few dominate. * **Avoid for** — a plain ranking (MiniBar) or parts of a single whole (SegmentedBar). ## Variants [#variants] ```tsx <ParetoStrip data={causes} threshold={false} />`" > <span className="inline-flex flex-col gap-2"> <ParetoStrip data="[ { label: "Timeouts", value: 38 }, { label: "OOM", value: 24 }, { label: "Deploy", value: 15 }, { label: "Config", value: 9 }, { label: "Network", value: 7 }, { label: "Auth", value: 4 }, ]" maxItems="3" title="Rolled up" width="240" height="26" /> <ParetoStrip data="[ { label: "Timeouts", value: 38 }, { label: "OOM", value: 24 }, { label: "Deploy", value: 15 }, { label: "Config", value: 9 }, { label: "Network", value: 7 }, { label: "Auth", value: 4 }, ]" threshold="false" title="No threshold" width="240" height="26" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <ParetoStrip data="[ { label: "Timeouts", value: 90 }, { label: "OOM", value: 6 }, { label: "Deploy", value: 4 }, ]" unit="causes" metric="incidents" title="One dominant cause" width="240" height="26" /> ``` ```tsx `" > <ParetoStrip data="[{ label: "a", value: 0 }]" metric="incidents" title="Nothing recorded" width="240" height="26" /> ``` ## Why this default [#why-this-default] The accent stops at the crossing, because the chart's one job is to say where to stop reading. The cumulative scale is fixed 0–100% and shares the full plot height — never rescaled to make the curve look steeper — and 80% is a **reference** default you can move or turn off, never a claimed law. `Other` is rendered honestly at its true size but always last and never counted among the vital few; if it towers over the top cause, that usually means `maxItems` is set too aggressively. ## Accessibility [#accessibility] The accessible name states the vital-few count and its cumulative — **"Top 1 of 3 causes account for 90% of incidents."** — or, when there is no threshold (or no ranked cause reaches it), the top cause and its share, as in the rolled-up demo above: **"Timeouts leads at 39%."** The interactive entry steps the bars and announces each bar's share and running cumulative; **T** jumps to the crossing bar. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value }[]` | Categories with magnitudes — the component sorts descending. | | `threshold` | `number \| false` | Cumulative reference line % (default 80 — a working reference, not a law). | | `maxItems` | `number` | Categories beyond maxItems roll up into Other (default 8, always last). | | `unit` | `string` | Category noun for the summary (default 'causes'). | | `metric` | `string` | Total-metric noun for the summary (default 'the total'). | | `label` | `"count" \| "none"` | 'K of N → cum%' in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # PartitionStrip (/docs/charts/partition-strip) PartitionStrip answers "what is the whole made of — and what are the big parts made of — with parentage visible?". Parents sit on the top row with widths proportional to their share of the whole, and each parent's children tile the exact x-range beneath it. Two aligned rows beat a treemap because alignment is the comparison channel — and two levels is a hard limit, because deeper hierarchies become unreadable texture at this size. ```tsx `" > <PartitionStrip data="[ { label: "JS", children: [{ label: "react", value: 28 }, { label: "vendor", value: 12 }, { label: "app", value: 8 }] }, { label: "CSS", children: [{ label: "tailwind", value: 16 }, { label: "custom", value: 8 }] }, { label: "img", value: 18 }, { label: "font", value: 10 }, ]" title="Bundle composition" width="320" height="30" /> ``` ## Install [#install] ```tsx import { PartitionStrip } from "@microcharts/react/partition-strip"; <PartitionStrip data={bundle} title="Bundle composition" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — bundle / storage / budget composition, two-level breakdowns. * **Avoid for** — deep hierarchies (unreadable at this size) or flat parts (SegmentedBar). ## Variants [#variants] ```tsx `" > <PartitionStrip data="[ { label: "JS", children: [ { label: "react", value: 28 }, { label: "vendor", value: 12 }, { label: "app", value: 8 }, ], }, { label: "CSS", children: [ { label: "tailwind", value: 16 }, { label: "custom", value: 8 }, ], }, { label: "img", value: 18 }, ]" emphasis="react" title="react emphasised" width="320" height="30" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <PartitionStrip data="[ { label: "img", value: 18 }, { label: "font", value: 10 }, { label: "css", value: 6 }, ]" title="Flat parts" width="220" height="24" /> ``` ```tsx `" > <PartitionStrip data="[ { label: "JS", children: [ { label: "react", value: 28 }, { label: "vendor", value: 12 }, ], }, { label: "CSS", children: [{ label: "tailwind", value: 16 }] }, ]" title="Squeezed" width="220" height="18" /> ``` ## Why this default [#why-this-default] Two aligned rows because alignment is the comparison — you can see at a glance that a child sits under its parent and how much of it that child is. A treemap discards that alignment and a flat SegmentedBar discards the hierarchy entirely. Grandchildren are ignored with a dev warning, on purpose: three levels of nesting at 24px is texture, not information. ## Accessibility [#accessibility] The accessible name names the biggest leaf and its parent — **"3 groups, 5 parts; largest JS → react (31% of the whole)."** The interactive entry roves within a row with ←/→ and moves between a parent and its children with ↑/↓, announcing each node's share of the whole and of its parent. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label, value?, children? }[]` | Two-level hierarchy. | | `emphasis` | `string` | Accents one node and its lineage. | | `labels` | `boolean` | Parent-row labels with size drop-out. | | `colors` | `string[]` | Per-group colours, cycled; overrides --mc-cat-N. Accent/neutral roles keep. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # PercentileLadder (/docs/charts/percentile-ladder) PercentileLadder answers "what does the tail look like — not just the median?". Ticks at the chosen percentiles sit on a zero-anchored track; graduated height and accent make the **tail** read strongest. Tick distances carry the story, so the origin is never cropped — and a log transform (for long latency tails) is never silent: an in-chart `log` tag renders when it applies. ```tsx i < 130 ? 90 + (i % 50) : i < 180 ? 150 + ((i * 7) % 320) : i < 196 ? 480 + ((i * 11) % 900) : 1500 + ((i * 13) % 800), )} title="Request latency" />`" > <PercentileLadder data="Array.from({ length: 200 }, (_, i) => (i < 130 ? 90 + (i % 50) : i < 180 ? 150 + ((i * 7) % 320) : i < 196 ? 480 + ((i * 11) % 900) : 1500 + ((i * 13) % 800)))" title="Request latency" width="240" height="18" /> ``` ## Install [#install] ```tsx import { PercentileLadder } from "@microcharts/react/percentile-ladder"; <PercentileLadder data={Array.from({ length: 200 }, (_, i) => i < 130 ? 90 + (i % 50) : i < 180 ? 150 + ((i * 7) % 320) : i < 196 ? 480 + ((i * 11) % 900) : 1500 + ((i * 13) % 800), )} format={{ style: "unit", unit: "millisecond" }} title="Request latency" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — latency SLOs in a sentence, the tail per endpoint in tables, payment-size spread. * **Avoid for** — the odds of an outcome (QuantileDots) or the full distribution shape (MicroBox). ## Variants [#variants] ```tsx i < 130 ? 90 + (i % 50) : i < 180 ? 150 + ((i * 7) % 320) : i < 196 ? 480 + ((i * 11) % 900) : 1500 + ((i * 13) % 800), ); <PercentileLadder data={latencies} scale="log" /> <PercentileLadder data={latencies} ps={[50, 95, 99.9]} label="values" /> <PercentileLadder data={latencies} marks="dot" /> // value labels and the summary format through Intl — "1.661 ms", not "1,661 ms" <PercentileLadder data={latencies} label="values" format={{ style: "unit", unit: "millisecond", maximumFractionDigits: 0 }} locale="de-DE" />`" > <span className="inline-flex flex-col gap-2"> <PercentileLadder data="Array.from({ length: 200 }, (_, i) => i < 130 ? 90 + (i % 50) : i < 180 ? 150 + ((i * 7) % 320) : i < 196 ? 480 + ((i * 11) % 900) : 1500 + ((i * 13) % 800), )" scale="log" title="Log scale" width="220" height="18" /> <PercentileLadder data="Array.from({ length: 200 }, (_, i) => i < 130 ? 90 + (i % 50) : i < 180 ? 150 + ((i * 7) % 320) : i < 196 ? 480 + ((i * 11) % 900) : 1500 + ((i * 13) % 800), )" ps="[50, 95, 99.9]" label="values" title="Strict SLOs" width="220" height="20" /> <PercentileLadder data="Array.from({ length: 200 }, (_, i) => i < 130 ? 90 + (i % 50) : i < 180 ? 150 + ((i * 7) % 320) : i < 196 ? 480 + ((i * 11) % 900) : 1500 + ((i * 13) % 800), )" marks="dot" title="Dot marks" width="220" height="18" /> <PercentileLadder data="Array.from({ length: 200 }, (_, i) => i < 130 ? 90 + (i % 50) : i < 180 ? 150 + ((i * 7) % 320) : i < 196 ? 480 + ((i * 11) % 900) : 1500 + ((i * 13) % 800), )" label="values" format="{ style: "unit", unit: "millisecond", maximumFractionDigits: 0 }" locale="de-DE" title="de-DE locale" width="260" height="18" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <PercentileLadder data="[7, 7, 7, 7]" title="All equal" width="120" height="14" /> ``` ```tsx `" > <PercentileLadder data="[0, 10, 100, 1000]" scale="log" title="Falls back" width="120" height="14" /> ``` ```tsx `" > <PercentileLadder data="[10, 20, 30, 90, 900]" title="Too narrow for labels" width="40" height="14" /> ``` ## Why this default [#why-this-default] The default linear track is zero-anchored — tick **distances** carry the story, so cropping the origin would distort every gap between percentiles. Height and accent grow toward the tail because the tail, not the median, is usually the SLO question. A log transform for long tails is never silent: it only applies when every sample is strictly positive, and an in-chart `log` tag renders whenever it does, so the axis is never misread as linear. ## Accessibility [#accessibility] The accessible name states every marked percentile and the tail's multiple of the median — **"p50 124.5, p90 488.1, p99 1,661.13 — the slowest 1% take 13.3× the median."** The interactive entry roves ticks with ←/→ (Home/End jump to the ends), announcing each tick's value and its multiple of the median (**"p99: 1,661.13 — 13.3× the median."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Raw sample; quantiles are derived. | | `ps` | `number[]` | Percentiles to mark (default [50, 90, 99], 2–4). | | `scale` | `"linear" \| "log"` | Log for long tails (falls back on any value ≤ 0; renders a log tag). | | `label` | `"ps" \| "values" \| "both" \| "none"` | What the tick labels state. | | `marks` | `"tick" \| "dot"` | Tick marks (default) or dot marks — dots read calmer over dense text. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # PercentileTrace (/docs/charts/percentile-trace) PercentileTrace answers "is this entity's standing rising or slipping inside the pack?". It traces one **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, not estimates — so the only line on the chart is the entity itself, drifting through a known landscape. ```tsx `" > <PercentileTrace data="[40, 46, 52, 58, 63, 68, 72, 76, 79, 81]" unit="week" label="last" title="Standing" width="260" height="30" /> ``` ## Install [#install] ```tsx import { PercentileTrace } from "@microcharts/react/percentile-trace"; <PercentileTrace data={ranks} title="Standing" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — one player's or product's rank drifting over time, whether a standing has crossed into the top or bottom of the pack, a percentile KPI where the population context matters. * **Avoid for** — a raw value over time (Sparkline) or one absolute number vs a target (Bullet / Delta). ## Variants [#variants] ```tsx <PercentileTrace data={[40, 46, 52, 58, 63, 68, 72, 76, 79, 81]} showBands={false} />`" > <span className="inline-flex flex-col gap-1.5"> <PercentileTrace data="[40, 46, 52, 58, 63, 68, 72, 76, 79, 81]" unit="week" title="with bands" width="220" height="28" /> <PercentileTrace data="[40, 46, 52, 58, 63, 68, 72, 76, 79, 81]" showBands="false" unit="week" title="no bands" width="220" height="28" /> </span> ``` 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 (a support ticket's backlog rank, say). The line already encodes the direction, so the color is only a redundant cue — never the sole signal. ```tsx `" > <PercentileTrace data="[78, 72, 64, 55, 47, 40, 34, 29, 26, 24]" positive="down" unit="week" title="down is good" width="220" height="28" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <PercentileTrace data="[63]" unit="week" title="Single reading" width="140" height="26" /> ``` ```tsx `" > <PercentileTrace data="[102, 88, 96]" unit="week" title="Clamped ranks" width="180" height="26" /> ``` ```tsx `" > <PercentileTrace data="[40, 55, 68, 81.5]" format="{ maximumFractionDigits: 1 }" locale="de-DE" label="last" unit="week" title="Localized percentile" width="180" height="26" /> ``` 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. ## Why this default [#why-this-default] The full 0–100 axis with fixed bands, because a percentile is a standing *within a population* — truncating the axis would hide how much headroom or floor is left, and re-estimating the bands from the single traced series would be a fiction. The middle-half and near-full fields are exact by construction, so the chart shows one honest line over a landscape you can trust, never a thicket of competing series. ## Accessibility [#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](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `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` | (interactive) Reading noun for the interactive announcement (default 'step'). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # PhaseTrace (/docs/charts/phase-trace) PhaseTrace answers "how do two coupled signals move *together*?". Plotting one against the other as a single trajectory turns lag into loops and regimes into clusters — structure that two separate sparklines hide. Path order carries time, and the current state is a directed endpoint with an arrowhead, so "now, and how it got here" reads at a glance. ```tsx { const t = (i / 40) * Math.PI * 2; return { x: 55 + Math.cos(t) * 22, y: 110 + Math.sin(t - 0.9) * 40 }; })} xLabel="CPU" yLabel="Latency" title="Phase portrait" />`" > <PhaseTrace data="Array.from({ length: 40 }, (_, i) => { const t = (i / 40) * Math.PI * 2; return { x: 55 + Math.cos(t) * 22, y: 110 + Math.sin(t - 0.9) * 40 }; })" xLabel="CPU" yLabel="Latency" title="Phase portrait" width="110" height="100" /> ``` ## Install [#install] ```tsx import { PhaseTrace } from "@microcharts/react/phase-trace"; <PhaseTrace data={trajectory} xLabel="CPU" yLabel="Latency" title="Phase portrait" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — coupled-signal phase portraits (CPU × latency, inflation × unemployment). * **Avoid for** — reading exact values (DualSparkline) or a single series (Sparkline). ## Variants [#variants] ```tsx { const t = (i / 40) * Math.PI * 2; return { x: 55 + Math.cos(t) * 22, y: 110 + Math.sin(t - 0.9) * 40 }; })} tail={0.4} startDot />`" > <PhaseTrace data="Array.from({ length: 40 }, (_, i) => { const t = (i / 40) * Math.PI * 2; return { x: 55 + Math.cos(t) * 22, y: 110 + Math.sin(t - 0.9) * 40 }; })" xLabel="CPU" yLabel="Latency" tail="0.4" title="Longer tail" width="110" height="100" /> ``` ```tsx `" > <PhaseTrace data="[ { x: 1200, y: 4500 }, { x: 1450, y: 4100 }, { x: 1800, y: 3600 }, ]" xLabel="Requests" yLabel="Errors" locale="de-DE" title="Localized coordinates" width="90" height="80" /> ``` With a `locale`, the accessible summary's coordinates follow that locale's own grouping — "1.800" in German, not "1,800". In-chart marks carry no text, so only the announced numbers change. ## Edge cases [#edge-cases] ```tsx `" > <PhaseTrace data="[{ x: 55, y: 62 }]" xLabel="CPU" yLabel="Latency" title="One observation" width="80" height="72" /> ``` ```tsx ({ x: 40, y: 40 }))} xLabel="CPU" yLabel="Latency" />`" > <PhaseTrace data="Array.from({ length: 8 }, () => ({ x: 40, y: 40 }))" xLabel="CPU" yLabel="Latency" title="No motion" width="80" height="72" /> ``` A single observation draws only the accent endpoint dot — there's no history to trail and no motion for an arrowhead to point along. When every point in the tail window is coincident (or nearly so, within 0.5% of the combined axis span), the heading resolves to the fifth, explicit "steady" state rather than a jittery direction from noise. ## Why this default [#why-this-default] A muted trail with an accent tail because "now, and how it got here" is the question — the eye lands on the recent motion first, then reads the history. Axis and scale choices are stated, never silently transformed: the axes are named in the summary, and the domains are always linear. The tail, endpoint, and arrowhead trio may be restyled but never all removed, because the recoverable time direction is what separates a phase trace from a scatter. ## Accessibility [#accessibility] The accessible name states the current point and heading, with the y-axis named first — for the hero example above, **"Latency vs CPU: now 76.729, 75.163; heading down-right."** The interactive entry steps through the trajectory in time order with ←/→, announcing each point's index and its value on both named axes. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ x, y }[]` | Two synchronized signals, time-ordered. | | `xLabel / yLabel` | `string` | Axis names — the summary reads them. | | `xDomain` | `[number, number]` | Fix the x-axis range (default: the data's x-extent). | | `domain` | `[number, number]` | Fix the y-axis range (default: the data's y-extent). | | `tail` | `number` | Fraction of points drawn in accent (recent motion). | | `grid` | `boolean` | Quadrant hairlines for regime reads. | | `startDot` | `boolean` | Anchor the path's origin for full-journey reads (default false). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # PictogramRow (/docs/charts/pictogram-row) PictogramRow answers "how many of the N units are filled?" — ●●●○○ — counts a human can verify by counting. Filled vs hollow is a shape difference too, never opacity alone, and unit size is constant: scaling glyphs with value is the classic pictogram lie this component refuses to tell. ```tsx <span className="text-lg"> {"The coalition holds "} <PictogramRow value="5" total="8" title="Committee seats held" style="{ width: "4.5em", height: "0.9em" }" /> {" of the seats."} </span> ``` ## Install [#install] ```tsx import { PictogramRow } from "@microcharts/react/pictogram-row"; <PictogramRow value={5} total={8} title="Committee seats held" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — seats, slots, and ratings in a sentence; capacity rows in tables. * **Avoid for** — more than 20 units (counting fails; use Progress) or continuous ratios (Progress). ## Variants [#variants] ```tsx `" > <PictogramRow value="2.5" total="4" title="True partial" width="90" height="18" /> ``` ```tsx `" > <PictogramRow value="2.5" total="4" fractional="round" title="Whole seats" width="90" height="18" /> ``` ```tsx `"> <PictogramRow value="3" total="5" shape="square" title="Squares" width="90" height="18" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <PictogramRow value="3" total="0" title="No capacity" width="90" height="18" /> ``` ```tsx `"> <PictogramRow value="-2" total="4" title="Deficit" width="90" height="18" /> ``` ```tsx `"> <PictogramRow value="9" total="8" title="Over capacity" width="90" height="18" /> ``` A `total` of 0 (or non-finite) draws nothing and the summary is "No data." — there is no meaningful row to count. A negative value renders every unit hollow, and the summary still states the true number ("-2 of 4.") rather than clamping to 0. A value past the total fills every unit — never more than `total` units drawn — but the summary keeps the honest count ("9 of 8.") with a dev-time warning, so the overflow is never hidden. ## Why this default [#why-this-default] Clip over round — the partial unit is real data, drawn as a true circular segment (not a `clipPath`, which would need generated ids that break server rendering determinism). Overflow renders all units filled but the summary keeps the true numbers ("9 of 8.") with a dev warning; the chart never silently caps the figure. ## Accessibility [#accessibility] The accessible name is the count — **"3 of 5."** — with the context noun coming from your `title` ("Committee seats held. 3 of 5."). The interactive entry re-announces when the value changes, and roving the units announces each one on its own: on the 5-of-8 demo at the top of this page, the fourth unit says "Unit 4 of 8 — filled." A unit reads as empty, filled, or, for a genuinely partial one, the percentage it holds. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | Filled units (may be fractional). | | `total` (required) | `number` | Unit count. | | `shape` | `"dot" \| "square"` | Squares pack tighter in table cells. | | `fractional` | `"clip" \| "round"` | Clip shows the true partial unit; round for seat-like units. | | `renderPoint` | `(unit) => ReactNode` | Custom unit glyph (star ratings) — the one sanctioned customization. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # PolarClock (/docs/charts/polar-clock) PolarClock answers "what's the shape of the day or week cycle — when is it busy?" Each value in the cycle becomes a radial bar at its fixed angle, growing outward from an inner baseline; longer bars are busier times. Midnight (or your week-start) sits at 12 o'clock and the cycle runs clockwise, so the rhythm of a metric across the cycle is immediately legible. ```tsx <PolarClock data="Array.from({ length: 24 }, (_, h) => (h === 14 ? 312 : h === 4 ? 20 : 80 + h))" now="14" title="Traffic by hour" size="72" /> ``` ## Install [#install] ```tsx import { PolarClock } from "@microcharts/react/polar-clock"; <PolarClock data={byHour} now={14} title="Traffic by hour" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — the shape of a 24-hour or 7-day cycle, when a metric is busy across the cycle, or a compact seasonal read in a KPI card. * **Avoid for** — exact value comparison (unroll the cycle into a `SparkBar`), a non-cyclic trend (`Sparkline`), or more than a few dozen segments. ## Variants [#variants] ```tsx (h === 14 ? 312 : h === 4 ? 20 : 80 + h)); const week = [120, 200, 180, 210, 260, 90, 60]; <PolarClock data={byHour} label="max" /> <PolarClock data={week} mode="opacity" />`" > <span className="inline-flex gap-6 items-center"> <PolarClock data="Array.from({ length: 24 }, (_, h) => (h === 14 ? 312 : h === 4 ? 20 : 80 + h))" label="max" size="64" summary="false" /> <PolarClock data="[120, 200, 180, 210, 260, 90, 60]" mode="opacity" size="56" summary="false" /> </span> ``` ```tsx (h === 14 ? 312 : h === 4 ? 20 : 80 + h)); <PolarClock data={byHour} labels={false} />`" > <PolarClock data="Array.from({ length: 24 }, (_, h) => (h === 14 ? 312 : h === 4 ? 20 : 80 + h))" labels="false" size="64" summary="false" /> ``` ```tsx (h === 14 ? 1240 : h === 4 ? 20 : 80 + h)); <PolarClock data={byHour} label="max" locale="de-DE" />`" > <PolarClock data="Array.from({ length: 24 }, (_, h) => (h === 14 ? 1240 : h === 4 ? 20 : 80 + h))" label="max" locale="de-DE" title="Localized peak" size="64" /> ``` ## Why this default [#why-this-default] The channel is radial **length from the inner baseline**, not sector area. Equal-value bars at the rim span more area than ones near the hub, so an area reading would exaggerate the outer segments — the inner radius is nonzero precisely to curb that distortion, and the docs ask you to compare lengths, not wedges. Bars are always zero-anchored at that baseline. For very small sizes where length is hard to judge, `mode="opacity"` switches the channel to a five-step fill — a radial `ActivityGrid` — which is a deliberate, named change of encoding, not a cosmetic one. A `null` segment leaves a gap (the baseline ring shows the hole) because missing is not the same as zero. The four cardinal ticks default **on** because a bare ring of bars is rotationally ambiguous — without a mark for "12 o'clock" there is no way to tell where the cycle starts, so "when is it busy" can't be answered from the static frame alone. The four ticks are merged into one path (a single node), so the orientation cue is free of the usual label-drop-out tradeoff — set `labels={false}` only when the shape itself is the whole story and the axis genuinely doesn't matter. ## Edge cases [#edge-cases] ```tsx `"> <PolarClock data="Array(24).fill(null)" title="No data yet" size="56" /> ``` ```tsx `"> <PolarClock data="Array(24).fill(50)" title="Steady" size="56" /> ``` ## Accessibility [#accessibility] The accessible name states the peak and the quiet point of the cycle — **"Peaks at 14:00 (1.240); quietest 04:00."** — with hour labels for a 24-segment cycle and weekday names for a 7-segment one. The interactive entry lets you arrow through the segments circularly, each announced with its label and value through a polite live region, and the accented `now` segment carries position and color, never color alone. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | One value per cycle division (24 hourly, 7 daily, any n). | | `now` | `number` | Index of the current segment to accent. | | `inner` | `number` | Inner radius fraction r0 — the zero baseline bars grow from (default 0.35). | | `mode` | `"length" \| "opacity"` | Radial bars (default) or fixed-length 5-step fill. | | `origin` | `number` | Index rendered at 12 o'clock (week-start / midnight). | | `labels` | `boolean` | Hairline cardinal ticks at 0/¼/½/¾ — the at-rest orientation cue. Default true. | | `segmentFormat` | `(index, n) => string` | Segment index → label (default: HH:00 for n=24, weekday for n=7, else index). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # ProgressRing (/docs/charts/progress-ring) ProgressRing answers "how complete is this?" at icon size, where a linear bar doesn't fit. The start angle is fixed at 12 o'clock and the caps are butt-cut — the two quiet ways rings inflate progress, both removed. It is never a gauge: no needle, no red zone. ```tsx `" > <ProgressRing value="0.68" label="percent" size="48" title="Backup" style="{ width: 72, height: 72 }" /> ``` ## Install [#install] ```tsx import { ProgressRing } from "@microcharts/react/progress-ring"; <ProgressRing value={0.68} title="Backup" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — tab headers, KPI card corners, cooldowns and retry timers (`sweep`). * **Avoid for** — precise reads (Progress — the % label is the datum there). ## Variants [#variants] ```tsx `" > <ProgressRing value="0.68" size="40" title="Cooldown" style="{ width: 56, height: 56 }" /> ``` ```tsx `"> <ProgressRing value="0.68" weight="6" size="40" title="Thick ring" style="{ width: 56, height: 56 }" /> ``` ```tsx `"> <ProgressRing value="0.68" label="percent" locale="de-DE" title="Localized percent" size="40" style="{ width: 56, height: 56 }" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <ProgressRing value="1.4" label="percent" title="Over budget" size="40" style="{ width: 56, height: 56 }" /> ``` ```tsx `"> <ProgressRing value="Number.NaN" label="percent" title="Unknown" size="40" style="{ width: 56, height: 56 }" /> ``` ## Why this default [#why-this-default] Butt caps and a fixed start: rounded caps overstate small fractions, and variable start angles make identical fractions look different. Past 100% the ring clamps while the center label carries the true percent — same contract as Progress. A full circle is drawn as two half-arcs (SVG cannot draw a single 360° arc). ## Accessibility [#accessibility] The accessible name reuses the progress wording — **"68% complete."**, or **"32% remaining."** in sweep mode. The interactive entry announces only at 25/50/75/100% threshold crossings — a streaming value never spams the screen reader. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The progressed amount. | | `max` | `number` | Denominator (default 1). | | `sweep` | `boolean` | Countdown: the REMAINING wedge shrinks. | | `weight` | `number` | Ring thickness (viewBox units). | | `label` | `"none" \| "percent"` | Centered figure (≥ 20 px rendered). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Progress (/docs/charts/progress) Progress answers "how far along is this, exactly?". The bar gives the instant read; the percent label *is* the datum — a bare bar is decoration. The track never shrinks for the label (the viewBox widens instead), so fractions stay comparable down a table column. ```tsx <Progress value="0.68" title="Onboarding" width="160" height="22" /> ``` ## Install [#install] ```tsx import { Progress } from "@microcharts/react/progress"; <Progress value={0.68} title="Onboarding" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — KPI cards, table completion columns, step counts (`segments`). * **Avoid for** — icon-size slots (ProgressRing) or composition (SegmentedBar). ## Variants [#variants] ```tsx `" > <Progress value="3" max="5" segments="5" label="fraction" title="Steps" width="160" height="22" /> ``` ```tsx <Progress value={0.68} label="none" />`" > <span className="inline-flex items-center gap-4"> <Progress value="34" max="50" label="value" title="Value label" width="140" height="22" /> <Progress value="0.68" label="none" title="Bare bar" width="110" height="22" /> </span> ``` ```tsx `" > <Progress value="0.68" positive="down" title="Budget burn" width="160" height="22" /> ``` ```tsx `"> <Progress value="34" max="50" label="value" locale="de-DE" title="Localized" width="140" height="22" /> ``` With `label="percent"` (the default) the accessible name follows `format`/`locale` too — "68 %" under `de-DE` rather than the English "68%". ## Edge cases [#edge-cases] ```tsx `" > <Progress value="112" max="100" title="Overshoot" width="160" height="22" /> ``` ```tsx `"> <Progress value="0" title="Not started" width="160" height="22" /> ``` ```tsx 0 — an empty track, // not an invented fraction <Progress value={5} max={0} title="Unknown goal" />`" > <Progress value="5" max="0" title="Unknown goal" width="160" height="22" /> ``` `max <= 0` (or a non-finite `value`/`max`) renders an empty track with no fill, and the label becomes an em dash ("—") rather than a fabricated number — the accessible name says "No data." instead of computing a meaningless ratio. A `value` of `0` renders a real, empty-but-present bar (not the no-data state), so "not started" and "unmeasurable" stay visually distinct. ## Why this default [#why-this-default] The percent label is on by default because it is the datum — the bar alone can't say "68%". Past 100% the bar clamps at full but the label carries the true figure ("112%"): the number and the bar only ever disagree in that one documented case, and the number wins. `max <= 0` renders an empty track and says "No data." rather than inventing a fraction. `max` — not `total` — is the deliberate exception across the library: every other denominator prop names a discrete count (`total` on IconArray, TallyMarks, Honeycomb…), but Progress tracks a continuous goal that can be overshot, so it keeps the word that says "ceiling," not "count." ## Accessibility [#accessibility] The accessible name is the completion — **"68% complete."**, or **"3 of 5 steps."** when segmented, or **"32% remaining."** with `positive="down"`. The interactive entry re-announces through a polite live region, throttled to whole-percent changes so a streaming value doesn't spam screen readers, and the fill-width transition is gated on reduced motion. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The progressed amount. | | `max` | `number` | Denominator (default 1). | | `segments` | `number` | Discrete-chunk track — the chart says step count, not ratio. | | `label` | `"percent" \| "value" \| "fraction" \| "none"` | The direct label; percent is the default datum. | | `positive` | `"up" \| "down"` | down = burn-down wording (summary only; the bar stays factual). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # QuadrantDot (/docs/charts/quadrant-dot) QuadrantDot answers "where does this item sit in the 2×2 — against the field?". A focal dot is placed by 2-D position, a hairline cross marks the split (the domain midpoints by default, always overridable but **never hidden**), and the peers show as tiny muted ghosts. The read is quadrant **membership** first; exact position is the second read — which is why it lives at glyph scale. ```tsx <QuadrantDot data="{ x: 3, y: 9 }" field="[ { x: 2, y: 8 }, { x: 8, y: 9 }, { x: 3, y: 7 }, { x: 9, y: 2 }, { x: 7, y: 3 }, { x: 1, y: 1 }, { x: 5, y: 6 }, { x: 6, y: 8 }, { x: 4, y: 3 }, { x: 8, y: 5 }, { x: 2, y: 4 }, { x: 7, y: 7 }, { x: 3, y: 2 }, { x: 6, y: 1 }, ]" xDomain="[0, 10]" domain="[0, 10]" xLabel="effort" yLabel="impact" title="Effort vs impact" width="96" height="96" /> ``` ## Install [#install] ```tsx import { QuadrantDot } from "@microcharts/react/quadrant-dot"; <QuadrantDot data={item} field={backlog} xLabel="effort" yLabel="impact" title="Effort vs impact" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — the classic prioritization 2×2 (one cell per initiative in a table), an effort-vs-impact read in a KPI card, any "which quadrant, against the field" decision. * **Avoid for** — a full scatter plot (MicroScatter) or a single ranked list (MiniBar). ## Variants [#variants] ```tsx <QuadrantDot data={item} field={backlog} quadrants={["quick win", "big bet", "skip", "time sink"]} />`" > <span className="inline-flex gap-4 items-center"> <QuadrantDot data="{ x: 3, y: 9 }" xDomain="[0, 10]" domain="[0, 10]" split="[5, 5]" xLabel="effort" yLabel="impact" width="72" height="72" /> <QuadrantDot data="{ x: 3, y: 9 }" field="[ { x: 2, y: 8 }, { x: 8, y: 9 }, { x: 9, y: 2 }, { x: 6, y: 1 }, { x: 4, y: 3 }, ]" xDomain="[0, 10]" domain="[0, 10]" quadrants="["quick win", "big bet", "skip", "time sink"]" width="72" height="72" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <QuadrantDot data="{ x: 5, y: 5 }" field="[ { x: 1, y: 5 }, { x: 8, y: 5 }, ]" xLabel="effort" yLabel="impact" title="Flat impact" width="72" height="72" /> ``` ```tsx `"> <QuadrantDot data="{ x: 5, y: 5 }" field="[ { x: 5, y: 5 }, { x: 1, y: 1 }, ]" xLabel="effort" yLabel="impact" title="Coincident peer" width="72" height="72" /> ``` ```tsx `"> <QuadrantDot data="{ x: Number.NaN, y: 5 }" title="Bad input" width="72" height="72" /> ``` When every field value on one axis equals the focal's, that axis's domain collapses to a point — the split line on that axis is dropped rather than drawn at an arbitrary spot, while the other axis's split still renders. A peer exactly on top of the focal is still counted (distance 0) and sorts first in the interactive entry's nearest-first order. A non-finite focal position draws no marks at all — no cross, no tint, no peers — and carries the "No data." summary, the same degenerate path an empty series takes elsewhere in the library. ## Why this default [#why-this-default] 24×24, because the 2×2 is a **position** read, not a scatter plot — you want to know the quadrant at a glance, and the exact coordinates only when you look closer. The split is data, not decoration: it renders wherever the split truly is and is always overridable, never invisible. With the axes unlabeled at glyph size, the `title` and `summary` are load-bearing — skipping them is the one named anti-pattern for this chart, so always pass `xLabel`, `yLabel`, and a `title`. ## Accessibility [#accessibility] The accessible name states the focal position and the axis-relative quadrant — **"Impact 9, effort 3 — in the high-impact, low-effort quadrant."** — adding how crowded that quadrant is when a `field` is given, or your own words via `quadrants={["quick win", …]}`. The interactive entry starts on the focal, then cycles peers nearest-first — each announced with its coordinates and quadrant. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ x; y }` | The focal item's 2-D position. | | `field` | `{ x; y }[]` | The peer set — omit for a lone glyph. | | `xDomain` | `[number, number]` | The x-axis range (default: derived from the data); domain stays the y-axis. | | `domain` | `[number, number]` | The y-axis range (default: derived from the data). | | `split` | `[number, number]` | The quadrant boundary (default domain midpoints) — never hidden. | | `quadrants` | `[TL, TR, BL, BR]` | Names in reading order — summaries only, never rendered. | | `xLabel / yLabel` | `string` | Axis nouns for the summary — pass them, the axes are unlabeled at glyph size. | | `region` | `boolean` | Faint tint on the focal's quadrant (default true; false for dense grids). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # QuantileDots (/docs/charts/quantile-dots) QuantileDots answers "what are the odds?" — in **countable** form. It's a quantile dotplot: each dot is an equal-probability quantile, so a dot is roughly a **1-in-N chance**, not a raw observation. Add a `threshold` and the plot turns from shape into odds: the dots past the line are re-inked and ringed, and the summary reads **"N in 20"** — because odds you can count beat odds you must trust, and a frequency reads truer than a bare percentage. ```tsx <QuantileDots data="Array.from({ length: 200 }, (_, i) => Math.round(4 + (i % 30) * 0.35 + ((i * 7) % 13) * 1.1 + (i % 50 === 0 ? 20 : 0)), )" threshold="15" format="{ style: "unit", unit: "minute", unitDisplay: "short", maximumFractionDigits: 0 }" title="Bus wait" width="260" height="30" /> ``` ## Install [#install] ```tsx import { QuantileDots } from "@microcharts/react/quantile-dots"; <QuantileDots data={waits} threshold={15} format={(n) => `${n} min`} title="Bus wait" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a "will we miss the SLA?" read in a sentence, odds you can count in a KPI card, a posterior communicated as frequency rather than percent. * **Avoid for** — a precise distribution shape (HistogramStrip) or one estimate's interval (GradedBand). ## Variants [#variants] ```tsx <QuantileDots data={waits} threshold={10} side="below" />`" > <span className="inline-flex flex-col gap-1.5"> <QuantileDots data="Array.from({ length: 200 }, (_, i) => Math.round(4 + (i % 30) * 0.35 + ((i * 7) % 13) * 1.1 + (i % 50 === 0 ? 20 : 0)), )" count="15" threshold="15" format="{ style: "unit", unit: "minute", unitDisplay: "short", maximumFractionDigits: 0 }" title="15 dots" width="220" height="28" /> <QuantileDots data="Array.from({ length: 200 }, (_, i) => Math.round(4 + (i % 30) * 0.35 + ((i * 7) % 13) * 1.1 + (i % 50 === 0 ? 20 : 0)), )" threshold="10" side="below" format="{ style: "unit", unit: "minute", unitDisplay: "short", maximumFractionDigits: 0 }" title="under 10 min" width="220" height="28" /> </span> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, the announced threshold follows that locale's own grouping and decimal marks. ```tsx `" > <QuantileDots data="Array.from({ length: 200 }, (_, i) => Math.round(4000 + (i % 30) * 350 + ((i * 7) % 13) * 1100 + (i % 50 === 0 ? 20000 : 0)), )" threshold="15000" format="{ style: "unit", unit: "minute", unitDisplay: "narrow" }" locale="de-DE" title="Localized threshold" width="220" height="26" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <QuantileDots data="[]" title="No samples" width="140" height="20" /> ``` ```tsx `"> <QuantileDots data="[7, 7, 7, 7, 7]" title="Certain outcome" width="140" height="20" /> ``` ```tsx `"> <QuantileDots data="Array.from({ length: 200 }, (_, i) => Math.round(4 + (i % 30) * 0.35 + ((i * 7) % 13) * 1.1))" threshold="9999" side="above" title="Threshold past the max" width="140" height="20" /> ``` Empty data draws nothing and the summary says so plainly. An all-equal sample collapses every dot into one column — genuine certainty, not a rendering glitch. A threshold outside the observed range reads as 0 in N (or N in N) — the count is always honest about what fraction of the field it's actually catching. ## Why this default [#why-this-default] 20 dots, because odds you can count beat odds you must trust — a reader subitizes a handful of highlighted dots faster than they parse "48%". Each dot is an equal-probability quantile, **not** a raw observation, and the summary always frames the answer as a frequency ("10 in 20"), never a bare percentage. Dots past the threshold are re-inked **and** ringed, so the count survives grayscale, print, and forced-colors. ## Accessibility [#accessibility] The accessible name states the odds in frequency form — **"8 in 15 chances above 15 min."** — or, without a threshold, "Most likely …; range …". The interactive entry is a probe: hovering or arrowing moves a live threshold and the count past it recomputes as you go. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Raw sample or posterior draws — the component derives the quantile dots. | | `count` | `number` | Number of quantile dots (default 20; 15–20 recommended; capped at 25). | | `threshold` | `number` | The decision line — turns the plot from shape into odds. | | `side` | `"above" \| "below"` | Which side of the threshold is the event being counted. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # QueueDepth (/docs/charts/queue-depth) QueueDepth answers "is the backlog draining or growing?". It draws the queue **depth** as a zero-anchored area — a stock, not a rate — against a dashed **capacity** hairline. Wherever the depth runs above capacity, the top edge is re-stroked in the negative ink, so a breach is a change in *shape* as well as color. The endpoint carries the current value and a trend glyph (▴/▾) fit over the last quarter of the window. ```tsx <QueueDepth data="[42, 55, 70, 88, 96, 120, 150, 182, 214]" capacity="100" title="Support queue" width="260" height="30" /> ``` ## Install [#install] ```tsx import { QueueDepth } from "@microcharts/react/queue-depth"; <QueueDepth data={[42, 55, 70, 88, 96, 120, 150, 182, 214]} capacity={100} title="Support queue" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a support-queue backlog in a KPI card, a work-in-progress stock against its WIP limit, will-it-drain in a tab header. * **Avoid for** — a rate rather than a stock (Sparkline) or a single count (Delta). ## Variants [#variants] ```tsx <QueueDepth data={backlog} /> <QueueDepth data={backlog} capacity={100} label="none" />`" > <span className="inline-flex flex-col gap-1.5"> <QueueDepth data="[214, 190, 150, 120, 96, 70, 48]" capacity="100" title="Draining" width="220" height="28" /> <QueueDepth data="[42, 55, 70, 88, 96, 120, 150, 182, 214]" title="No capacity reference" width="220" height="28" /> <QueueDepth data="[42, 55, 70, 88, 96, 120, 150, 182, 214]" capacity="100" label="none" title="No label" width="220" height="28" /> </span> ``` ```tsx `" > <QueueDepth data="[420, 560, 720, 880, 1040, 1280, 1560, 1880, 2140]" capacity="1000" locale="de-DE" title="Localized backlog" width="220" height="28" /> ``` With a `locale`, both the endpoint label and the accessible summary's numbers follow that locale's own grouping — the summary reads **"2.140 queued, 2,1× capacity, growing over the last quarter."** in German, not "2,140 queued, 2.1× capacity". ## Edge cases [#edge-cases] ```tsx `" > <QueueDepth data="[42, 55, 70, 88, 96, 120, 150, 182, 214]" title="No capacity" width="220" height="28" /> ``` ```tsx `"> <QueueDepth data="[90, 70, 50, 30]" capacity="100" title="Draining" width="220" height="28" /> ``` ```tsx `" > <QueueDepth data="[10, null, 40, null, 80, 120]" capacity="100" title="Gaps" width="220" height="28" /> ``` With no `capacity`, the area still draws and the summary reads **"214 queued, growing over the last quarter."** — no capacity clause, because there's nothing to compare against. A queue that stays under capacity reports **"30 queued, within capacity, draining over the last quarter."** and never re-strokes the edge. Gaps (`null`/`NaN`/`±Infinity`) split the area into separate runs rather than drawing a line across missing periods. ## Why this default [#why-this-default] The capacity hairline plus the negative re-stroke, because "are we keeping up?" is a threshold question — a breach should read instantly and survive greyscale, so it changes the edge's *shape*, not only its color. The trend glyph is deliberately low-precision: it's fit over the last quarter of the window as a direction cue, and the summary states that window in words ("over the last quarter") rather than implying a forecast the data can't support. ## Accessibility [#accessibility] The accessible name states the current depth, the capacity relationship, and the trend — **"214 queued, 2.1× capacity, growing over the last quarter."**. When the depth stays under capacity the middle clause becomes "within capacity"; with no `capacity` it drops entirely. The interactive entry steps the periods, announcing each depth and whether it's above capacity (**"t8: 214 queued, above capacity."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Backlog depth per period (≥ 0). null / NaN / ±Infinity are gaps. | | `capacity` | `number` | Steady-state capacity: a dashed hairline; spans above it re-stroke negative. | | `label` | `"last" \| "none"` | Endpoint value + trend glyph (▴/▾), default 'last', or nothing. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # RateVolume (/docs/charts/rate-volume) RateVolume answers "the rate moved — on what volume?". A precise rate line rides over deliberately low-precision **ghost volume bars** — the denominator. There is no prop to remove the bars: a rate without its denominator is the lie this type exists to prevent. A 4.1% conversion rate reads very differently on 38 events than on 3,800. ```tsx <RateVolume data="[ { rate: 0.023, volume: 220 }, { rate: 0.025, volume: 190 }, { rate: 0.028, volume: 160 }, { rate: 0.029, volume: 130 }, { rate: 0.031, volume: 110 }, { rate: 0.034, volume: 90 }, { rate: 0.036, volume: 66 }, { rate: 0.041, volume: 38 }, ]" format="{ style: "percent", maximumFractionDigits: 1 }" minVolume="50" label="last" title="Conversion rate" width="260" height="28" /> ``` ## Install [#install] ```tsx import { RateVolume } from "@microcharts/react/rate-volume"; <RateVolume data={periods} minVolume={50} title="Conversion rate" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a conversion / error rate with its denominator, a KPI card where the rate is the headline, spotting a big rate move on thin volume. * **Avoid for** — volume itself needing a precise read (pair a SparkBar) or a plain series (Sparkline). ## Variants [#variants] ```tsx <RateVolume data={periods} curve="step" />`" > <span className="inline-flex flex-col gap-1.5"> <RateVolume data="[ { rate: 0.023, volume: 220 }, { rate: 0.028, volume: 160 }, { rate: 0.031, volume: 110 }, { rate: 0.036, volume: 66 }, { rate: 0.041, volume: 38 }, ]" format="{ style: "percent", maximumFractionDigits: 1 }" minVolume="50" title="Low-volume flag" width="220" height="26" /> <RateVolume data="[ { rate: 0.023, volume: 220 }, { rate: 0.028, volume: 160 }, { rate: 0.031, volume: 110 }, { rate: 0.036, volume: 66 }, { rate: 0.041, volume: 38 }, ]" format="{ style: "percent", maximumFractionDigits: 1 }" curve="step" title="Per-period step" width="220" height="26" /> </span> ``` ```tsx `" > <RateVolume data="[ { rate: 0.023, volume: 220 }, { rate: 0.041, volume: 38 }, ]" format="{ style: "percent", maximumFractionDigits: 1 }" volumeFormat="{ maximumFractionDigits: 0 }" locale="de-DE" title="Localized rate" width="180" height="26" /> ``` `format` and `volumeFormat` both take `Intl.NumberFormatOptions` and share the same `locale` — the rate label reads "4,1 %" and volumes group with a period ("3.800") under `de-DE`, matching that locale's own conventions rather than a hardcoded English format. ## Edge cases [#edge-cases] ```tsx `" > <RateVolume data="[ { rate: 0.02, volume: 200 }, { rate: Number.NaN, volume: 0 }, { rate: 0.03, volume: 180 }, ]" format="{ style: "percent", maximumFractionDigits: 0 }" title="Gap on zero volume" width="140" height="26" /> ``` ```tsx `"> <RateVolume data="[]" title="No periods yet" width="140" height="26" /> ``` A period with zero (or non-finite) volume renders no bar and no rate mark, and the line gaps across it instead of interpolating through a period nothing was measured on — the interactive entry announces that period as **"no events"** rather than a rate. With no data at all, the chart renders an empty root and the accessible name says **"No data."** ## Why this default [#why-this-default] The volume bars are muted and unlabeled because they answer "enough?", not "how many?". A rate on **zero** volume is undefined regardless of the input — the line breaks and no mark is drawn, because a rate nobody generated should never be plotted. `minVolume` makes a thin denominator visible right at the mark: below it the rate point renders hollow, a shape cue that survives forced-colors and print. ## Accessibility [#accessibility] The accessible name always pairs the rate with its volume — **"4.1% on 38 events (low volume); up from 2.3% across 5 periods."**. The interactive entry steps the periods and its live region never states a rate without the volume it stands on, announcing "no events" for a zero-volume period. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ rate; volume }[]` | Periods, oldest first — each a rate and the volume it was measured on. | | `minVolume` | `number` | Below it, the rate mark renders hollow — 'insufficient denominator'. | | `curve` | `"linear" \| "step"` | Step suits per-period aggregate rates. | | `volumeFormat` | `Intl.NumberFormatOptions \| (n) => string` | Volume has different units than rate; formatted separately. | | `unit` | `string` | Noun for the volume unit in the summary (default 'events'). | | `volumeDomain` | `[number, number]` | Volume (bar) domain — defaults to [0, max], zero-anchored. | | `label` | `"last" \| "none"` | Endpoint rate in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # RetentionCurve (/docs/charts/retention-curve) RetentionCurve answers "do they stay — and does the curve plateau?". It draws a **step** line (cohort periods are discrete) on a scale **locked to 0–100%** — the full range is the honest frame for a share, so the floor is never truncated to manufacture drama. When the curve flattens, a dotted plateau marker appears; a peer curve can ride behind as a subordinate ghost. ```tsx `" > <RetentionCurve data="[1, 0.72, 0.55, 0.47, 0.42, 0.4, 0.39, 0.385, 0.382, 0.38, 0.379, 0.378]" unit="week" label="last" title="W12 cohort" width="260" height="30" /> ``` ## Install [#install] ```tsx import { RetentionCurve } from "@microcharts/react/retention-curve"; <RetentionCurve data={cohort} unit="week" title="W12 cohort" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a cohort retention curve in a KPI card, your decay vs an industry benchmark, spotting whether retention plateaus (or keeps leaking). * **Avoid for** — a continuous signal (Sparkline) or one-number retention (Progress / Delta). ## Variants [#variants] ```tsx <RetentionCurve data={[1, 0.72, 0.55, 0.47, 0.42, 0.4, 0.39, 0.385, 0.382, 0.38]} curve="smooth" />`" > <span className="inline-flex flex-col gap-1.5"> <RetentionCurve data="[1, 0.72, 0.55, 0.47, 0.42, 0.4, 0.39, 0.385, 0.382, 0.38]" benchmark="[1, 0.6, 0.44, 0.37, 0.33, 0.3, 0.29, 0.285, 0.282, 0.28]" unit="week" title="vs industry" width="220" height="28" /> <RetentionCurve data="[1, 0.72, 0.55, 0.47, 0.42, 0.4, 0.39, 0.385, 0.382, 0.38]" curve="smooth" unit="week" title="smooth" width="220" height="28" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <RetentionCurve data="[1]" unit="week" title="Week zero only" width="140" height="26" /> ``` ```tsx `" > <RetentionCurve data="[100, 72, 55, 47, 42, 40, 39]" unit="week" title="Percent-scale input" width="180" height="26" /> ``` ```tsx `" > <RetentionCurve data="[1, 0.72, 0.55, 0.47, 0.42, 0.4, 0.39]" unit="week" label="last" locale="de-DE" title="Localized retention" width="180" height="26" /> ``` A single period is too short for plateau detection (the window needs at least four finite points) and renders as a single step with no visible line. `data` accepts either a 0–1 fraction or a 0–100 percent series — whichever the max value implies — so a raw percent export renders identically to its fraction form without a manual divide. With a `locale`, the percent label and every announced number follow that locale's own formatting. ## Why this default [#why-this-default] Step line plus the full 0–100% range, because retention is a discrete share, not a continuous signal — a smoothed curve implies between-period values that never existed, and a truncated floor exaggerates or hides the drop. The plateau marker appears **only** when the mean period-over-period change over the tail falls below half a point — never as decoration — and the benchmark stays a subordinate dashed ghost, never a second competing line. ## Accessibility [#accessibility] The accessible name states the final retention and, when detected, the plateau — **"38% retained after 10 weeks; curve plateaus from week 6."**. The interactive entry steps the periods and announces each period's retention alongside the benchmark's. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Fraction retained per period (0–1 or 0–100); period 0 is typically 1.0. | | `benchmark` | `number[]` | Peer/industry curve, drawn as a subordinate dashed ghost. | | `plateau` | `boolean` | Detect + mark a plateau (default true). | | `curve` | `"step" \| "smooth"` | Step (default — cohorts are discrete) or smooth (editorial). | | `unit` | `string` | Period noun for the summary (default 'period'). | | `label` | `"last" \| "none"` | Final retention in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # RubricStrip (/docs/charts/rubric-strip) RubricStrip answers "how did this thing score per criterion — with each criterion's importance visible — without a fake composite number?". Each bar's length is its score and its thickness is its weight share, so the things that matter most are literally the biggest marks. There is no total bar, and none may be added — the type exists to resist collapsing quality into one number. ```tsx `" > <RubricStrip data="[ { label: "Correctness", score: 0.92, weight: 3 }, { label: "Coverage", score: 0.78, weight: 2 }, { label: "Clarity", score: 0.65, weight: 1 }, { label: "Style", score: 0.41, weight: 1 }, ]" target="0.7" title="Model eval" width="240" height="44" /> ``` ## Install [#install] ```tsx import { RubricStrip } from "@microcharts/react/rubric-strip"; <RubricStrip data={[ { label: "Correctness", score: 0.92, weight: 3 }, { label: "Coverage", score: 0.78, weight: 2 }, { label: "Clarity", score: 0.65, weight: 1 }, { label: "Style", score: 0.41, weight: 1 }, ]} title="Model eval" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — model / code-review scorecards, weighted vendor comparison. * **Avoid for** — a single criterion (Bullet) or parts of a whole (SegmentedBar). ## Variants [#variants] ```tsx `" > <RubricStrip data="[ { label: "Lint", score: 1 }, { label: "Types", score: 1 }, { label: "Tests", score: 0.8 }, { label: "Docs", score: 0.5 }, ]" title="Checklist" width="240" height="44" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <RubricStrip data="[{ label: "Bonus", score: 2, weight: 1 }]" title="Clamped" width="200" height="16" /> ``` ```tsx `"> <RubricStrip data="[{ label: "Overall fit", score: 0.83 }]" title="Single criterion" width="200" height="16" /> ``` ## Why this default [#why-this-default] Weight-as-thickness keeps "importance" visible where a table hides it — a light criterion that scores well can't visually outweigh a heavy one that scores poorly. The summary names the extremes, never a weighted average, because the whole point is that a single number throws away the structure. A `target` draws one honest pass line across every row instead. ## Accessibility [#accessibility] The accessible name names the extremes — **"4 criteria; highest Lint (1), lowest Docs (0.5)."** The interactive entry roves the criteria, announcing each one's score and its weight share of the total (**"Coverage: 0.78, weight 29% of total."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label, score, weight? }[]` | Criteria; weights default equal. | | `target` | `number` | Pass target — one tick across all rows. | | `labels` | `boolean` | Criterion names in the left gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # RugStrip (/docs/charts/rug-strip) RugStrip answers "where do the raw observations actually sit?". Every tick is one real observation — no binning, no jitter, no thinning. Stacked duplicates darken (tiered opacity), and `markValue` tells the chart's strongest single story: one raw value against the field. ```tsx `" > <span className="text-lg"> {"Your offer sits "} <RugStrip data="[42, 48, 51, 53, 55, 58, 61, 63, 66, 71, 55, 52, 49, 58, 62, 75, 83]" markValue="78" title="Pay band" style="{ width: "7em", height: "0.9em" }" /> {" inside the band."} </span> ``` ## Install [#install] ```tsx import { RugStrip } from "@microcharts/react/rug-strip"; <RugStrip data={salaries} markValue={yourOffer} title="Pay band" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — "you are here" in a pay band, raw spread beside a stat, margin composition under a Sparkline. * **Avoid for** — more than \~400 observations (a rug promises raw marks and never downsamples; use HistogramStrip) or trends over time (Sparkline). ## Variants [#variants] ```tsx `"> <RugStrip data="[42, 48, 55, 58, 61, 66, 71, 75]" markValue="62" title="Field plus you" style="{ width: 140, height: 14 }" /> ``` ```tsx `" > <RugStrip data="[50, 50, 50, 50, 62, 71]" title="Duplicates" style="{ width: 140, height: 14 }" /> ``` ```tsx `"> <RugStrip data="[42, 48, 55, 61, 71]" orientation="vertical" title="Vertical rug" style="{ width: 14, height: 80 }" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <RugStrip data="[]" title="No observations" style="{ width: 140, height: 14 }" /> ``` Empty data draws a quiet centered axis line — not a blank hole — so the strip still reads as "a rug with nothing on it" rather than a layout gap. ```tsx `"> <RugStrip data="[52]" title="One observation" style="{ width: 140, height: 14 }" /> ``` A single value (or an all-equal field) has a zero-span domain; the tick renders at the strip's midpoint instead of dividing by zero. ```tsx `"> <RugStrip data="[42, 48, 55, 61, 71]" markValue="120" title="Above the field" style="{ width: 140, height: 14 }" /> ``` A `markValue` outside the observed domain clamps to the nearest edge — it never escapes the box or silently rescales the field around it. ## Why this default [#why-this-default] Ticks sit at 35% opacity — singles stay visible while stacks read as density. Because a browser paints one path's stroke as a single operation, coincident ticks are bucketed into opacity tiers (35% / 60% / 85%) rather than relying on overlap compositing that never happens. Regular ticks are inset one unit so the full-height accent highlight reads "taller" without escaping the box. ## Accessibility [#accessibility] The accessible name is the distribution — **"8 values from 42 to 75, median 59.5."** The interactive entry walks observations in sorted order and announces each with its rank: **"48 — 2nd of 17."** The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Raw observations — position = value. | | `markValue` | `number` | One value emphasized against the field. | | `orientation` | `"horizontal" \| "vertical"` | Vertical rugs sit beside distributions. | | `domain` | `[number, number]` | Fix the scale across rows (rugs mislead worst under per-row autoscale). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # SegmentedBar (/docs/charts/segmented-bar) SegmentedBar answers "what is this made of, and in what proportions?". Segments always sum to the full bar; past `maxSegments` the tail rolls into a labeled "Other" — nothing is silently dropped. A flat bar beats a donut of the same data at every size we ship. ```tsx <SegmentedBar data="[ { label: "Chrome", value: 620 }, { label: "Safari", value: 240 }, { label: "Firefox", value: 90 }, { label: "Edge", value: 30 }, { label: "Arc", value: 20 }, ]" title="Browser share" width="220" height="20" /> ``` ## Install [#install] ```tsx import { SegmentedBar } from "@microcharts/react/segmented-bar"; <SegmentedBar data={mix} title="Browser share" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — traffic mix per table row, composition in KPI cards. * **Avoid for** — precise cross-row comparison (MiniBar) or negative parts (Waterfall). ## Variants [#variants] ```tsx `" > <SegmentedBar data="[ { label: "Chrome", value: 620 }, { label: "Safari", value: 240 }, { label: "Firefox", value: 140 }, ]" title="With percents" width="220" height="20" /> ``` ```tsx `" > <SegmentedBar data="[ { label: "Firefox", value: 90 }, { label: "Chrome", value: 620 }, { label: "Safari", value: 240 }, ]" order="desc" title="Ranked" width="220" height="20" /> ``` ```tsx `" > <SegmentedBar data="[ { label: "Chrome", value: 12400 }, { label: "Safari", value: 6200 }, ]" label="value" locale="de-DE" title="Localized values" width="220" height="20" /> ``` `label="value"` follows `format`/`locale` — 12400 reads "12.400" under `de-DE` rather than the English "12,400". `label="percent"` is unaffected: the largest-remainder shares are always plain integers, never locale-formatted, because a percent point is the same everywhere. ## Edge cases [#edge-cases] ```tsx `" > <SegmentedBar data="[ { label: "Chrome", value: 620 }, { label: "Safari", value: 240 }, { label: "Firefox", value: 90 }, { label: "Edge", value: 30 }, { label: "Arc", value: 12 }, { label: "Brave", value: 8 }, ]" label="percent" title="Six sources, five segments" width="220" height="20" /> ``` ```tsx `"> <SegmentedBar data="[{ label: "Chrome", value: 1 }]" label="percent" title="Single category" width="100" height="20" /> ``` Past `maxSegments` (default 5) the smallest categories merge into a labeled "Other" — nothing is dropped, only rolled up, and the interactive entry announces its member count. A single category still renders as one full-width, 100% segment rather than a special-cased bare bar. Negative values can't exist in a part-to-whole, so they're excluded from the bar entirely (not clamped to zero) and the component logs a dev warning steering toward Waterfall. ## Why this default [#why-this-default] Data order is the default — inherent sequences (funnel-like stages, weekday mixes) carry meaning that ranking destroys. Summary percents use largest-remainder rounding so they always sum to exactly 100; negative values are excluded with a dev warning (a part-to-whole cannot contain negative parts — use Waterfall). ## Accessibility [#accessibility] The accessible name is the full composition — **"Chrome 62%, Safari 24%, Firefox 9%, Edge 3%, Other 2%."** The interactive entry roves segments; the Other segment announces its member count (**"Other: 2%, 2 categories."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value }[]` | Parts of the whole. | | `maxSegments` | `number` | Rollup threshold — the tail becomes a labeled Other. | | `order` | `"data" \| "desc"` | Preserve inherent sequences or rank the composition. | | `label` | `"none" \| "percent" \| "value"` | Centered per segment (deterministic drop-out; default percent). | | `colors` | `string[]` | Per-segment colours, cycled; overrides --mc-cat-N. Other stays neutral. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Seismogram (/docs/charts/seismogram) Seismogram answers "when did things happen, and how hard?". Ticks read as a seismograph trace — centered on a midline and flaring symmetrically: presence is density texture, length is intensity. Long series collapse via max-per-bucket only — the spike is the chart's whole job, so it always survives, and the summary is always computed from the raw values, never the buckets. ```tsx `" > <Seismogram data="[1, 2, 1, 3, 2, 6, 2, 1, 0, 2, 1, 4, 9, 3, 1, 2, 0, 1, 3, 2, 7, 2, 1, 0, 2, 1, 5, 11, 3, 1]" title="Error bursts" width="240" height="36" /> ``` ## Install [#install] ```tsx import { Seismogram } from "@microcharts/react/seismogram"; <Seismogram data={burstsPerMinute} title="Error bursts" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — error bursts per service, alert density, activity texture in rows. * **Avoid for** — level tracking (Sparkline) or labeled events (EventTimeline). ## Variants [#variants] ```tsx `" > <Seismogram data="[1, 0, 2, 1, 3, 0, 1, 2, 0, 1, 1, 0, 2, 1, 3, 1, 0, 1, 2, 1]" mode="barcode" title="Deploys" width="180" height="22" /> ``` ```tsx `" > <Seismogram data="[3, -1, 4, -2, 1, 5, -3, 2, -1, 4, -2, 6, -4, 1, -2, 3, -1, 2]" positive="up" title="Net flow shocks" width="200" height="30" /> ``` ```tsx `" > <Seismogram data="[1, 2, 1, 3, 2, 6, 2, 1, 0, 2, 1, 4, 9, 3, 1, 2, 0, 1, 3, 2, 7, 2, 1, 0, 2, 1, 5, 11, 3, 1, 2, 1]" anomaly="6" title="Error bursts" width="240" height="36" /> ``` ```tsx `" > <Seismogram data="[3, -1, 4, -2, 12500, 5, -3, 2, -1, 4]" positive="up" format="{ maximumFractionDigits: 0 }" locale="de-DE" title="Localized magnitudes" width="200" height="30" /> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, the accessible summary's peak number follows that locale's own grouping ("12.500" in German, not "12,500"). Tick positions and lengths are unaffected; only the announced peak is localized. ## Edge cases [#edge-cases] ```tsx `" > <Seismogram data="[0, 0, 0, 0, 0, 0]" title="Quiet" width="160" height="20" /> ``` ```tsx (i === 210 ? 9 : i % 17 === 0 ? 2 : 0))} />`" > <Seismogram data="Array.from({ length: 300 }, (_, i) => (i === 210 ? 9 : i % 17 === 0 ? 2 : 0))" title="Long history" width="160" height="24" /> ``` ## Why this default [#why-this-default] A centered seismograph trace over bottom-anchored bars: the symmetric flare reads as event intensity rather than inviting the bar-to-bar magnitude comparison the strip is too small to support — and it stays visually distinct from SparkBar. Barcode mode is documented as presence-only — a uniform tick is not intensity. `anomaly` flags spikes at or above a threshold in the alert token; the flag is redundant with tick length, never color alone. A quiet strip renders its baseline at rest, never a blank hole. ## Accessibility [#accessibility] The accessible name counts the events — **"29 events, peak 11."**, or **"No events."** for a quiet strip. The interactive entry steps slots with position readouts ("Point 2 of 5: 3."), announces quiet slots as "no data", and Home/End jump to the first/last event. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | Per-slot event intensity; 0/null = quiet. | | `mode` | `"intensity" \| "barcode"` | Barcode collapses heights — pure occurrence density. | | `positive` | `"up" \| "down"` | Polarity coloring of signed ticks. | | `anomaly` | `number` | Flag spikes: \|v\| ≥ threshold flares in the alert token. | | `domain` | `[number, number]` | Fixed intensity scale across rows. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # ShiftHistogram (/docs/charts/shift-histogram) ShiftHistogram answers "did the fix actually change the distribution?". It mirrors two histograms around a center line — **before** upward (muted), **after** downward (accent) — on **shared bin edges**, with the median shift as the precise takeaway. Bar heights are per-side proportions on one shared scale, so a bigger sample on one side can't fake a shift. The mirror carries **identity**, not valence (up isn't "good") — that's the whole point of the symmetry. ```tsx <ShiftHistogram data="{ before: Array.from({ length: 100 }, (_, i) => 120 + (i % 40) - 20), after: Array.from({ length: 100 }, (_, i) => 96 + (i % 40) - 20), }" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" title="The fix" width="260" height="30" /> ``` ## Install [#install] ```tsx import { ShiftHistogram } from "@microcharts/react/shift-histogram"; <ShiftHistogram data={{ before, after }} title="The fix" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a "the fix, proven" read in a KPI card, before/after distributions in an experiments table, showing a change is real (not just a mean move). * **Avoid for** — a single distribution (HistogramStrip) or two labelled arms (ABStrips). ## Variants [#variants] ```tsx 120 + (i % 40) - 20); const after = Array.from({ length: 100 }, (_, i) => 96 + (i % 40) - 20); <ShiftHistogram data={{ before, after }} mode="overlay" /> <ShiftHistogram data={{ before, after: before }} />`" > <span className="inline-flex flex-col gap-2"> <ShiftHistogram data="{ before: Array.from({ length: 100 }, (_, i) => 120 + (i % 40) - 20), after: Array.from({ length: 100 }, (_, i) => 96 + (i % 40) - 20), }" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" mode="overlay" title="Overlay" width="240" height="26" /> <ShiftHistogram data="{ before: Array.from({ length: 100 }, (_, i) => 120 + (i % 40) - 20), after: Array.from({ length: 100 }, (_, i) => 120 + (i % 40) - 20), }" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" title="No shift" width="240" height="26" /> </span> ``` ```tsx `" > <ShiftHistogram data="{ before: [12000, 12400, 12800], after: [9600, 10000, 10400] }" locale="de-DE" title="Localized medians" width="200" height="26" /> ``` The median shift label and accessible summary follow `format`/`locale` — the before median above reads "12.400" under `de-DE` rather than the English "12,400". ## Edge cases [#edge-cases] ```tsx 120 + (i % 40) - 20); <ShiftHistogram data={{ before, after: [] }} format={(n) => Math.round(n) + " ms"} title="Awaiting after sample" />`" > <ShiftHistogram data="{ before: Array.from({ length: 100 }, (_, i) => 120 + (i % 40) - 20), after: [], }" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" title="Awaiting after sample" width="240" height="26" /> ``` ```tsx `"> <ShiftHistogram data="{ before: [], after: [] }" title="No data yet" width="200" height="26" /> ``` With one side empty the chart still renders the populated side's bins alone, and the summary names the gap directly — **"Median 116 ms; no after sample."** — never a fabricated shift. With both sides empty nothing is plottable and the accessible name says **"No data."** ## Why this default [#why-this-default] Mirror, because before/after symmetry makes the shift a visible displacement. The only normalization allowed is per-side proportions — each side's counts over its own n — on one shared height scale, so unequal sample sizes never fake a shift, and the rule is stated. The bins are shared across both sides always, and the medians are never smoothed or trimmed. Side identity rides on position (up vs before, down vs after) so it survives grayscale and forced-colors; the summary names the direction and, when the sample sizes differ, carries both. ## Accessibility [#accessibility] The accessible name states the median shift plainly — **"Median fell from 116 ms to 92 ms."** — appending "On N / M samples" when the sizes differ. The interactive entry steps the bins and announces each bin's before/after proportions; **M** jumps to the two median bins. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ before: number[]; after: number[] }` | The two samples — raw observations, shared bin edges are derived. | | `bins` | `number` | Shared bin count (default auto, Sturges capped at 12). | | `mode` | `"mirror" \| "overlay"` | Mirror (default) or after-as-outline over before fill. | | `seriesLabels` | `[string, string]` | Side identities for the summary (default ['before', 'after']). | | `label` | `"shift" \| "none"` | Signed median shift in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Slope (/docs/charts/slope) Slope answers "who rose and who fell between two moments — and did the order change?". Lines stay neutral until you declare `positive`: a rank change is not automatically good or bad. Both columns share one y-domain — per-column normalization would fake convergence. ```tsx `" > <Slope data="[ { label: "East", from: 40, to: 47 }, { label: "West", from: 55, to: 41 }, { label: "South", from: 30, to: 33 }, ]" title="Before vs after" width="130" height="90" /> ``` ## Install [#install] ```tsx import { Slope } from "@microcharts/react/slope"; <Slope data={cohorts} title="Before vs after" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — before/after experiments, rank shuffles, two-moment comparisons. * **Avoid for** — the path between the moments (Sparkline) or more than 7 categories. ## Variants [#variants] ```tsx <Slope data={rows} positive="up" highlight="West" />`" > <span className="inline-flex gap-6"> <Slope data="[ { label: "East", from: 40, to: 47 }, { label: "West", from: 55, to: 41 }, { label: "Mid", from: 20, to: 35 }, ]" label="both" title="Labeled" width="180" height="100" /> <Slope data="[ { label: "East", from: 40, to: 47 }, { label: "West", from: 55, to: 41 }, { label: "Mid", from: 20, to: 35 }, ]" positive="up" highlight="West" title="Valence" width="130" height="90" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <Slope data="[ { label: "East", from: 40, to: 47 }, { label: "New", from: NaN, to: 41 }, ]" title="New entrant" width="130" height="70" /> ``` ```tsx `"> <Slope data="[{ label: "East", from: 40, to: 47 }]" title="One category" width="90" height="60" /> ``` ```tsx `" > <Slope data="[ { label: "East", from: 4000, to: 4700 }, { label: "West", from: 5500, to: 4100 }, ]" label="both" locale="de-DE" title="Localized values" width="150" height="90" /> ``` A row missing one side (`from` or `to` as `NaN`) draws a short dashed stub toward the end it does have, rather than a full line — there's no second point to connect to, so nothing is interpolated. With a `locale`, both column labels and the announced values follow that locale's own grouping. ## Why this default [#why-this-default] A two-point line implies nothing about the path between — the docs steer to Sparkline when the journey matters. End labels drop deterministically, never by measurement: when the rows are denser than the label font (height ÷ count), and when the reserved label gutters would squeeze the two columns under \~35% of the width — in which case the reclaimed room goes back to the lines. Endpoints that would collide inside a column are nudged apart to a full glyph pitch instead of overlapping. A missing end renders a dashed stub and is announced "incomplete", never interpolated. ## Accessibility [#accessibility] The accessible name counts directions and leads with the biggest mover — **"3 categories: 2 up, 1 down. Largest change Mid, up 75%."** The interactive entry finds the nearest line under the pointer and roves categories ordered by their after-value, announcing each slope (**"East: 40 to 47, up 18%."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; from; to }[]` | Two aligned moments per category. | | `label` | `"none" \| "value" \| "label" \| "both"` | End labels; dropped deterministically when rows collide. | | `highlight` | `number \| string` | The one-vs-field editorial read. | | `positive` | `"up" \| "down"` | Direction valence; unset = neutral ink. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # SparkBar (/docs/charts/sparkbar) SparkBar renders discrete values as compact bars from a zero baseline. In `winloss` mode it collapses each value to its sign — a streak you can read at a glance: wins above the mid-line, losses below, and a tie (`0`) as a thin neutral dash on it. ```tsx <SparkBar data="[4, 6, 2, 8, 5, 9]" width="120" height="32" title="Deploys per day" /> ``` ## Install [#install] ```tsx import { SparkBar } from "@microcharts/react/sparkbar"; <SparkBar data={[4, 6, 2, 8, 5, 9]} title="Deploys per day" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — discrete magnitudes, win–loss streaks, period-over-period counts. * **Avoid for** — a continuous trend shape (use [Sparkline](/docs/charts/sparkline)) or hundreds of points, where bars become noise. ## Sizing [#sizing] `width` and `height` are viewBox units that also set the rendered pixel box. Omit them and drive the width from CSS for a chart that fills its container — the viewBox keeps the aspect ratio. ## Variants [#variants] ```tsx `"> <SparkBar data="[4, 6, 2, 8, 5, 9]" width="130" height="32" title="Magnitude" /> ``` ```tsx `"> <SparkBar data="[1, -1, 1, 1, -1, 1, -1]" width="130" height="32" mode="winloss" title="Win–loss streak" /> ``` ```tsx `" > <SparkBar data="[1, -1, 0, 1, 0, -1, 1]" width="130" height="32" mode="winloss" title="Win–loss–tie streak" /> ``` ```tsx `"> <SparkBar data="[4, 6, 2, 8, 5, 9]" width="130" height="32" label="last" title="With endpoint label" /> ``` ```tsx `"> <SparkBar data="[4200, 6100, 2800, 8600]" width="130" height="32" label="last" locale="de-DE" title="Localized" /> ``` The endpoint label and accessible summary both follow `format`/`locale` — 8600 reads "8.600" under `de-DE` rather than the English "8,600". ## Edge cases [#edge-cases] ```tsx `"> <SparkBar data="[]" title="No deploys yet" width="100" height="32" /> ``` ```tsx `"> <SparkBar data="[6]" title="One deploy" width="40" height="32" /> ``` An empty series renders no bars and an accessible name that says so, rather than a flat or invented baseline. A single value still renders as one zero-anchored bar — `winloss` mode treats it the same way a longer streak would: a lone win, loss, or tie. ## Why this default [#why-this-default] Bars, not a line, because SparkBar's job is discrete magnitudes — deploy counts, daily totals — where each period is its own thing, not a sampled point on a continuous curve. Zero-anchored always: a bar whose length doesn't start at zero misstates its magnitude. `winloss` mode goes further and discards magnitude entirely on purpose, collapsing each value to a three-state streak (win above the mid-line, loss below, tie a thin dash on it) because for a streak, sign is the whole story and a magnitude axis would just be noise. Sign is doubled by position AND color everywhere signed data appears, so direction survives forced-colors and never depends on color alone. In `bar` mode the endpoint bar takes the accent — "where did it land" is usually the first question a run of counts answers; in `winloss` mode it keeps its win/loss/tie color instead, because there the sign is what matters at every position, endpoint included. ## Accessibility [#accessibility] Announced from the data — the example above reads: > Deploys per day. Trending up 125%. Range 2 to 9. Last value 9. Sign is doubled by position (above or below the baseline), never by color alone, so the chart survives forced-colors and color-blind viewing. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Values; negatives dip below the baseline. | | `mode` | `"bar" \| "winloss"` | Magnitude bars, or a win/loss/tie streak (sign only). | | `gap` | `number` | Empty fraction of each slot (0–0.9). | | `label` | `"none" \| "last"` | Direct endpoint value label. | | `positive` | `"up" \| "down"` | "up" (default); "down" flips which sign is good. | | `title` | `string` | Accessible name; joins the auto summary. | | `summary` | `string \| false` | Override or disable the auto summary. | | `locale` | `string \| string[]` | BCP 47 locale(s) for the endpoint label and summary. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Sparkline (/docs/charts/sparkline) Sparkline draws a compact trend over ordered values. Reach for it when direction and shape matter more than exact points — inline in a sentence, inside a table cell, or as the quiet backbone of a KPI card. ```tsx <Sparkline data="[3, 5, 4, 8, 6, 9]" width="120" height="32" title="Weekly revenue" /> ``` ## Install [#install] ```tsx import { Sparkline } from "@microcharts/react/sparkline"; <Sparkline data={[3, 5, 4, 8, 6, 9]} title="Weekly revenue" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — an inline trend, a table-cell trend, a KPI sparkline, dense dashboards. * **Avoid for** — part-to-whole comparisons or reading exact category values. Use [SparkBar](/docs/charts/sparkbar) for discrete magnitudes, or [Bullet](/docs/charts/bullet) for a value against a target. ## Sizing [#sizing] `width` and `height` are viewBox units that also set the rendered pixel box. Omit them and drive the width from CSS for a chart that fills its container — the viewBox keeps the aspect ratio. ## Variants [#variants] Shape, fill, a normal-range band, and dots are all props — same data, different read. Flip any of them to the Code tab. ```tsx `"> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="120" height="32" curve="smooth" title="Smooth curve" /> ``` ```tsx `"> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="120" height="32" title="Filled area" /> ``` ```tsx `"> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="120" height="32" band="[4, 8]" title="Normal-range band" /> ``` ```tsx `"> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="130" height="32" dots="minmax" label="last" title="Min/max dots" /> ``` ```tsx `" > <Sparkline data="[3, 5, 4, 8, 6, 9, 2, 7]" width="130" height="36" dots="minmax" label="minmax" title="Extremes labelled" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <Sparkline data="[3, 5, null, null, 6, 9, 4, 7]" width="130" height="32" title="Series with gaps" /> ``` ```tsx `"> <Sparkline data="[7]" width="80" height="32" title="One value" /> ``` ```tsx `"> <Sparkline data="[5, 5, 5, 5, 5, 5]" width="130" height="32" title="Flat series" /> ``` A `null` means "no measurement here" — the line breaks at the gap and never interpolates across it, so an outage can't masquerade as a smooth trend. A single point has no line to draw; it sits centered in the plot, visible as the default endpoint dot. An all-equal series renders on the vertical mid-line — a zero-span domain maps to the middle of the range, so flat data reads as level, not as bottomed-out. Past `maxPoints` (default 200) the drawn line decimates to a min/max-preserving envelope: every spike keeps its true position and height, gaps stay gaps, and the summary, dots, and hover values still come from the raw data — only the path gets lighter. Pass `maxPoints={Infinity}` to opt out. ```tsx i === 1500 ? 98 : 50 + Math.sin(i / 40) * 24 + ((i * 13) % 7), )} />`" > <Sparkline data="Array.from({ length: 2000 }, (_, i) => (i === 1500 ? 98 : 50 + Math.sin(i / 40) * 24 + ((i * 13) % 7)))" width="220" height="40" title="Two thousand points, one spike" /> ``` ## Four homes [#four-homes] The same chart, sized for four real contexts. Each preview is the public component plus `styles.css` — no docs-only wrappers. Sentence placements use `mc-inline`; see [Composition](/docs/composition) and [Sizing](/docs/sizing). ## Why this default [#why-this-default] A bare line plus one accent dot on the last point — no fill, no band, no min/max dots. The shape of the series is the whole story until you ask for more, and the endpoint dot marks where "now" is. Min/max dots, fill, and the band are opt-in because at word size they compete with the line for the same few pixels; adding them by default would make every sparkline noisier for the common case that only needs direction and range. Long series decimate to a min/max-preserving envelope rather than a naive stride sample, so a single spike at point 1,500 of 2,000 still shows up — silently dropping it would be the more common bug in a naive implementation, and a chart that hides its own spikes is dishonest by construction. ## Accessibility [#accessibility] By default the chart is an `img` whose accessible name is generated from the data. The example above is announced as: > Weekly revenue. Trending up 200%. Range 3 to 9. Last value 9. Pass a `title` to name it, or `summary={false}` to make it decorative when the surrounding text already says what it shows. The interactive entry adds a polite live region that reads each focused point as you arrow through it. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | The series. null/NaN are gaps. | | `curve` | `"linear" \| "smooth" \| "step"` | Line shape. | | `fill` | `boolean` | Zero-anchored area under the line. | | `band` | `[number, number]` | Constant normal-range band. | | `dots` | `"auto" \| "minmax" \| "none"` | Endpoint or min/max dots. | | `label` | `"none" \| "last" \| "minmax"` | Direct value labels: endpoint, or the extremes. | | `maxPoints` | `number` | Line-point cap (default 200); longer series decimate min/max-preserving. | | `title` | `string` | Accessible name; joins the auto summary. | | `summary` | `string \| false` | Override or disable the auto summary. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # SpiralYear (/docs/charts/spiral-year) SpiralYear answers "how did the year breathe?" It winds a calendar series onto an Archimedean spiral: the angle is the position in the year (January at 12 o'clock, running clockwise) and each turn outward is the next year. The value becomes a five-step opacity, so busy stretches read as darker arcs of the spiral. This is a **pattern instrument** — opacity is the weakest ordered channel, so for an exact day's value reach for `ActivityGrid` or `HeatStrip`. ```tsx <SpiralYear data="Array.from({ length: 52 }, (_, i) => { const s = Math.round(200 + 140 * Math.sin(((i - 8) / 52) * Math.PI * 2)); return i === 29 ? 480 : s; })" title="Seasonality" size="80" /> ``` ## Install [#install] ```tsx import { SpiralYear } from "@microcharts/react/spiral-year"; <SpiralYear data={byWeek} title="Seasonality" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — the seasonal shape of a year at a glance, spotting a busy season or a quiet stretch, or a compact "the year in one square". * **Avoid for** — reading an exact day's value (`ActivityGrid` / `HeatStrip`), a non-cyclic trend (`Sparkline`), or more than about three years. ## Variants [#variants] ```tsx { const s = Math.round(200 + 140 * Math.sin(((i - 8) / 52) * Math.PI * 2)); return i === 29 ? 480 : s; // a summer peak in week 30 }); <SpiralYear data={byWeek} mark="arc" /> <SpiralYear data={byWeek} steps={3} />`" > <span className="inline-flex gap-6 items-center"> <SpiralYear data="Array.from({ length: 52 }, (_, i) => { const s = Math.round(200 + 140 * Math.sin(((i - 8) / 52) * Math.PI * 2)); return i === 29 ? 480 : s; })" mark="arc" size="64" summary="false" /> <SpiralYear data="Array.from({ length: 52 }, (_, i) => { const s = Math.round(200 + 140 * Math.sin(((i - 8) / 52) * Math.PI * 2)); return i === 29 ? 480 : s; })" steps="3" size="56" summary="false" /> </span> ``` `locale` doesn't change any in-chart mark — opacity steps carry the value, never a printed number — but it does localize the peak and low values named in the accessible summary: ```tsx { const s = Math.round(200 + 140 * Math.sin(((i - 8) / 52) * Math.PI * 2)); return i === 29 ? 1480 : s; }); <SpiralYear data={byWeek} locale="de-DE" />`" > <SpiralYear data="Array.from({ length: 52 }, (_, i) => { const s = Math.round(200 + 140 * Math.sin(((i - 8) / 52) * Math.PI * 2)); return i === 29 ? 1480 : s; })" locale="de-DE" title="Localized summary" size="64" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <SpiralYear data="[80, 120, null, 90, 140]" title="With a gap" size="56" /> ``` ```tsx `"> <SpiralYear data="[]" title="Empty" size="56" /> ``` ## Why this default [#why-this-default] Month ticks are on by default because without a temporal anchor the spiral is just texture — the ticks are what make "when" readable. Five steps is the ceiling: ordered opacity supports about five discriminable levels, and more would be false precision. The spiral **radius encodes time only, never value** — an outer mark is simply a later date, not a bigger number. Two adjacent turns place different years at the same angle; that radial adjacency is calendar alignment, not similarity, and the chart never asks you to compare across it. A `null` day leaves a gap in the spiral, distinct from a faint step-one mark, because missing is not the same as low. ## Accessibility [#accessibility] The accessible name states the count, the peak, and the low — **"52 weeks; peak 1.480 in week 30, low in week 48."** (the `de-DE` localized demo). The interactive entry lets you arrow along the spiral chronologically, each mark announced with its period and value through a polite live region. Because the channel is ordinal opacity, the docs and summary steer any exact read to `ActivityGrid`. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | One value per day or week (cadence inferred from length). | | `cadence` | `"day" \| "week"` | Data cadence; inferred from length (≈52 → week, else day) when omitted. | | `startDate` | `string` | ISO date anchoring index 0 to a calendar angle. | | `steps` | `3 \| 5` | Opacity quantization (default 5). | | `monthTicks` | `boolean` | Faint radial month ticks (default true). | | `mark` | `"dot" \| "arc"` | Dots (default) or short arc segments. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # SpreadBand (/docs/charts/spread-band) SpreadBand answers "which of two series leads, by how much, and since when?" The signed gap between a subject and its reference is filled and split at every crossing, so who is ahead and when it last flipped both read at a glance. The reference whispers: dashed, thinner, neutral — direction is carried by the fill sign and the text, never color alone. ```tsx <SpreadBand data="[ { a: 8, b: 12 }, { a: 9, b: 12 }, { a: 11, b: 13 }, { a: 12, b: 13 }, { a: 14, b: 13 }, { a: 15, b: 14 }, { a: 17, b: 14 }, { a: 18, b: 14 }, { a: 20, b: 15 }, { a: 21, b: 15 }, { a: 23, b: 16 }, { a: 24, b: 16 }, ]" seriesLabels="["Organic", "Paid"]" title="Organic vs paid" width="220" height="30" /> ``` ## Install [#install] ```tsx import { SpreadBand } from "@microcharts/react/spread-band"; <SpreadBand data={pairs} seriesLabels={["Organic", "Paid"]} title="Organic vs paid" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — lead-vs-reference in KPI cards, actual-vs-plan where the flip matters. * **Avoid for** — 3+ series (SparkGroup), or unpaired series / different units (never dual axes). ## Variants [#variants] ```tsx `" > <SpreadBand data="[ { a: 8, b: 12 }, { a: 12, b: 13 }, { a: 14, b: 13 }, { a: 17, b: 14 }, { a: 20, b: 15 }, { a: 24, b: 16 }, ]" seriesLabels="["Organic", "Paid"]" label="none" title="No gutter label" width="220" height="30" /> ``` ```tsx `" > <SpreadBand data="[ { a: 18, b: 12 }, { a: 16, b: 12 }, { a: 14, b: 13 }, { a: 11, b: 13 }, { a: 9, b: 14 }, { a: 8, b: 14 }, ]" seriesLabels="["Latency", "Budget"]" positive="down" title="Lower is better" width="220" height="30" /> ``` ```tsx `" > <SpreadBand data="[ { a: 8000, b: 12000 }, { a: 9000, b: 12000 }, { a: 11000, b: 13000 }, { a: 12000, b: 13000 }, { a: 14000, b: 13000 }, { a: 15000, b: 14000 }, { a: 17000, b: 14000 }, { a: 18000, b: 14000 }, { a: 20000, b: 15000 }, { a: 21000, b: 15000 }, { a: 23000, b: 16000 }, { a: 24000, b: 16000 }, ]" seriesLabels="["Organic", "Paid"]" locale="de-DE" title="Localized values" width="230" height="30" /> ``` The gutter label and the hover readout follow the `locale`'s grouping — the German build reads the current gap as **+8.000** and the summary as "Organic leads Paid by 8.000; last crossed at point 5." ## Edge cases [#edge-cases] ```tsx `" > <SpreadBand data="[ { a: 10, b: 5 }, { a: 12, b: 6 }, { a: 14, b: 7 }, ]" seriesLabels="["A", "B"]" title="Never crosses" width="200" height="30" /> ``` ```tsx `" > <SpreadBand data="[ { a: 12, b: 12 }, { a: 15, b: 15 }, { a: 14, b: 14 }, { a: 18, b: 18 }, ]" title="Level throughout" width="200" height="30" /> ``` ```tsx `"> <SpreadBand data="[ { a: 12, b: 10 }, { a: 14, b: null }, { a: 13, b: 12 }, { a: 16, b: 13 }, ]" seriesLabels="["A", "B"]" title="Shared gaps" width="200" height="30" /> ``` A `null` in either series is a gap in **both** — the gap is undefined where a reading is missing, so the fill and both lines break at that index rather than inventing a value. Identical series read "The two series are level — no gap." and a subject that never falls behind reports "never crossed." ## Why this default [#why-this-default] One shared domain across both series — comparability is the whole point, so there are no dual axes and no per-series normalization. The gap is filled and split exactly at the interpolated crossings, so the eye lands on the flip without hunting. The reference whispers and the leader's sign is stated in text, so direction never rides on color alone. ## Accessibility [#accessibility] The accessible name states the lead, the current gap, and where the lines last crossed — **"Organic leads Paid by 8; last crossed at point 3."** Identical series read "The two series are level — no gap." The interactive entry announces the lead at each point (**"Point 12 of 12: Organic +8 over Paid."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ a: number \| null; b: number \| null }[]` | Paired readings — a is the subject, b the reference. | | `seriesLabels` | `[string, string]` | Names the two series in the summary and label. | | `positive` | `"up" \| "down"` | Which lead is the good valence; down flips the fill colors. | | `label` | `"gap" \| "none"` | Current signed gap in a right gutter (default gap). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # SproutRow (/docs/charts/sprout-row) SproutRow answers "how mature or healthy is each item in a small set?" Each item is one of four growth stages — **seed → sprout → leaf → bloom** — and the glyph height is strictly monotonic, so taller always means further along and the ordering reads without the legend. The stages are discrete and there are exactly four; there are no half-stages, because a growth metaphor must not fake continuity. ```tsx <SproutRow data="[ { label: "Acme", value: 3 }, { label: "Beta", value: 2 }, { label: "Gamma", value: 3 }, { label: "Delta", value: 1 }, { label: "Echo", value: 0 }, { label: "Foxtrot", value: 2 }, ]" title="Account health" height="30" step="24" /> ``` The key, shown once: **seed → sprout → leaf → bloom**. ## Install [#install] ```tsx import { SproutRow } from "@microcharts/react/sprout-row"; <SproutRow data={accounts} title="Account health" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — account or project maturity across a small set, a health column in a portfolio table, or per-item lifecycle in a KPI card. * **Avoid for** — continuous values (MiniBar), trends (Sparkline), or more than about twelve items. ## Variants [#variants] ```tsx <SproutRow data={[{ label: "A", value: 2 }, { label: "B", value: null }, { label: "C", value: 0 }]} />`" > <span className="inline-flex gap-6 items-center"> <SproutRow data="[ { label: "A", value: 0 }, { label: "B", value: 1 }, { label: "C", value: 2 }, { label: "D", value: 3 }, ]" label="value" height="26" step="20" /> <SproutRow data="[ { label: "A", value: 2 }, { label: "B", value: null }, { label: "C", value: 0 }, ]" height="24" step="22" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <SproutRow data="[]" title="No accounts" height="20" step="20" /> ``` ```tsx `"> <SproutRow data="[ { label: "A", value: 2 }, { label: "B", value: null }, ]" title="One account missing" height="20" step="20" /> ``` ```tsx `"> <SproutRow data="[ { label: "A", value: -3 }, { label: "B", value: 12 }, ]" title="Clamped stages" height="20" step="20" /> ``` Empty data draws just the frame. A `null` value renders only the soil tick — visibly distinct from a seed, which is stage 0 and gets its own glyph. Values outside `[0, 3]` round and clamp to the nearest real stage (seed or bloom) rather than drawing an out-of-bounds or fractional glyph. ## Why this default [#why-this-default] Labels are off by default because the row usually sits beside its own row label, and at micro scale the glyphs alone carry the ordering. The one-line key — seed → sprout → leaf → bloom — appears once above the demos, and after that the height does the work. A `null` value is a real gap: it draws only the soil tick, distinct from a seed, because "no data yet" is not "just planted". Presets recolor the glyphs but never reshape a stage; the four stages are fixed and never interpolated. ## Accessibility [#accessibility] The accessible name summarizes the row — **"4 items; 1 at bloom, 1 at seed."** The interactive entry roves the items with ←/→ (or hover), announcing each as **"Acme: bloom, stage 4 of 4."** — the stage name plus a 1-of-4 index — and reads "…: no data." for a missing item. A ring lifts the focused glyph. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label, value }[]` | value = stage 0–3. | | `labels` | `boolean` | Category labels under the slots. | | `label` | `"none" \| "value"` | Print the stage number above each glyph. | | `step` | `number` | Horizontal spacing between glyph slots (default 16; widens for labels). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # StackedArea (/docs/charts/stacked-area) StackedArea answers "how is the composition shifting over time?" Layer thickness is share; the stack always sums to 100%. Three series is the hard cap — beyond that, thickness at 16 px stops being readable. ```tsx <StackedArea data="[ { label: "Mobile", values: [30, 34, 36, 40, 44, 47, 52, 56, 58, 60, 63, 66] }, { label: "Web", values: [50, 48, 47, 45, 42, 41, 38, 36, 35, 33, 32, 30] }, { label: "API", values: [20, 18, 17, 15, 14, 12, 10, 8, 7, 7, 5, 4] }, ]" title="Traffic mix" width="220" height="30" /> ``` ## Install [#install] ```tsx import { StackedArea } from "@microcharts/react/stacked-area"; <StackedArea data={mix} title="Traffic mix" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — traffic/revenue mix in KPI cards, share-shift stories in sentences. * **Avoid for** — 4+ series, or exact values over time (SparkGroup of Sparklines). ## Variants [#variants] ```tsx <StackedArea data={mix} order="asc" /> <StackedArea data={mix} locale="de-DE" label="last" />`" > <span className="inline-flex flex-col gap-3"> <StackedArea data="[ { label: "Mobile", values: [30, 34, 36, 40, 44, 47, 52, 56, 58, 60, 63, 66] }, { label: "Web", values: [50, 48, 47, 45, 42, 41, 38, 36, 35, 33, 32, 30] }, { label: "API", values: [20, 18, 17, 15, 14, 12, 10, 8, 7, 7, 5, 4] }, ]" mode="ridge" title="Ridge skin" width="220" height="30" /> <StackedArea data="[ { label: "Mobile", values: [30, 34, 36, 40, 44, 47, 52, 56, 58, 60, 63, 66] }, { label: "Web", values: [50, 48, 47, 45, 42, 41, 38, 36, 35, 33, 32, 30] }, { label: "API", values: [20, 18, 17, 15, 14, 12, 10, 8, 7, 7, 5, 4] }, ]" order="asc" title="Ascending order" width="220" height="30" /> <StackedArea data="[ { label: "Mobile", values: [30, 34, 36, 40, 44, 47, 52, 56, 58, 60, 63, 66] }, { label: "Web", values: [50, 48, 47, 45, 42, 41, 38, 36, 35, 33, 32, 30] }, { label: "API", values: [20, 18, 17, 15, 14, 12, 10, 8, 7, 7, 5, 4] }, ]" locale="de-DE" label="last" title="Localized shares" width="220" height="30" /> </span> ``` `format`/`locale` control the share numbers — the accessible summary and endpoint labels follow the locale's own percent formatting ("66 %" in German, with a space before the sign, not "66%"). The stack itself never changes shape; only the announced and printed numbers localize. ## Edge cases [#edge-cases] ```tsx `"> <StackedArea data="[ { label: "A", values: [10] }, { label: "B", values: [5] }, ]" title="Single column" width="160" height="30" /> ``` ```tsx `" > <StackedArea data="[ { label: "A", values: [0, 0, 0, 0] }, { label: "B", values: [5, 5, 5, 5] }, ]" title="A series at zero" width="160" height="30" /> ``` A single column still stacks normally — share is well-defined from one point, it's just a vertical slice with no width to run across. A series pinned at zero collapses to a zero-height layer rather than distorting the others: the remaining series still sum to 100% of what's left. ## Why this default [#why-this-default] Values are normalized to shares before stacking, so the stack reads composition — not magnitude and composition tangled together. `order="asc"` puts the smallest series on top, where curvature distorts thickness the least. ## Accessibility [#accessibility] The accessible name is the share-shift read — **"3 series over 12 points; Mobile leads at 66% share."** The interactive entry announces every layer at once (**"Point 8 of 12: Mobile 56%, Web 36%, API 8%."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; values }[]` | ≤ 3 series (hard cap). | | `mode` | `"stacked" \| "ridge"` | Ridge = same stack, overlapping-crest skin. | | `order` | `"data" \| "asc"` | "asc" puts the smallest series on top (least distortion). | | `label` | `"last" \| "none"` | Endpoint share labels per series (deterministic drop-out). | | `labelAt` | `number` | Column whose shares feed label="last" (default: final column). The interactive entry passes the focused column so the labels track the crosshair. | | `curve` | `"linear" \| "smooth" \| "step"` | Line interpolation (default linear); ridge forces smooth. | | `colors` | `string[]` | Per-series colours, cycled; overrides --mc-cat-N. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # StarSpoke (/docs/charts/star-spoke) StarSpoke answers "what is this entity's profile across a few metrics — and which entity in a set is the odd one out?". Spokes radiate from the center and their length encodes each value. There is no connecting polygon, ever: the enclosed area of a radar chart lies about magnitude and axis order, and the research is clear that contour-free wins for spotting outliers. ```tsx <StarSpoke data="[ { label: "Speed", value: 0.9 }, { label: "Power", value: 0.6 }, { label: "Range", value: 0.5 }, { label: "Cost", value: 0.3 }, { label: "Ease", value: 0.7 }, ]" dots="tips" title="Product profile" size="110" /> ``` ## Install [#install] ```tsx import { StarSpoke } from "@microcharts/react/star-spoke"; <StarSpoke data={metrics} title="Product profile" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — entity profiles in small multiples, skill / capability comparison. * **Avoid for** — fewer than 3 metrics (PairedBars) or precise values (MiniBar). ## Variants [#variants] ```tsx `" > <StarSpoke data="[ { label: "Speed", value: 0.9 }, { label: "Power", value: 0.6 }, { label: "Range", value: 0.5 }, { label: "Cost", value: 0.3 }, { label: "Ease", value: 0.7 }, ]" compare="[0.5, 0.5, 0.5, 0.5, 0.5]" dots="tips" title="vs baseline" size="110" /> ``` `locale` doesn't change any in-chart mark — tip labels are metric names, never formatted numbers — but it does localize the extremes named in the accessible summary: ```tsx `" > <StarSpoke data="[ { label: "Speed", value: 1900 }, { label: "Power", value: 600 }, { label: "Range", value: 500 }, ]" domain="[0, 2000]" locale="de-DE" title="Localized summary" size="110" /> ``` ## Why this default [#why-this-default] Contour-free is the point: a connecting polygon is decoration that changes the read, exaggerating area for high-variance profiles and hiding the individual spoke lengths that actually matter for comparison. One shared domain governs every spoke in a glyph — mixed-domain metrics are the caller's normalization to state, so a set of small multiples stays honestly comparable. Every spoke sits at a fixed clock position (first at 12 o'clock, clockwise), so the axis order never shifts between instances — that fixed order, plus the default-on guide spokes, is what keeps a profile readable even where a metric's label doesn't seat. Tip labels seat at the rim, not the value tip, so a low-value spoke never drags its label into the hub. A label is dropped only when its estimated width exceeds the whole glyph; anything narrower is clamped into the reserved label ring instead, which keeps rim labels at distinct angles rather than dropping them. ## Edge cases [#edge-cases] ```tsx `" > <StarSpoke data="[ { label: "Reliability", value: 0.9 }, { label: "Throughput", value: 0.6 }, { label: "Cost efficiency", value: 0.5 }, ]" title="Small, long labels" size="48" /> ``` ```tsx `"> <StarSpoke data="[]" title="Empty" size="64" /> ``` ## Accessibility [#accessibility] The accessible name names the extremes — **"5 metrics; highest Speed (0.9), lowest Cost (0.3)."** The interactive entry rotates focus through the spokes with ←/→, announcing each metric and value. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label, value }[]` | 3–8 metrics on a shared domain. | | `dots` | `"tips" \| "none"` | `"tips"` draws endpoint dots to sharpen the outlier read. | | `guides` | `boolean` | Full-length guide spokes (read-back scaffold). | | `compare` | `number[]` | Muted ghost baseline spokes. | | `labels` | `boolean` | Spoke labels at the tips (default true; drop out below size 44). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # StationGlyph (/docs/charts/station-glyph) StationGlyph packs a full point observation into one character, the way a meteorologist's station model does: the center disc fills with sky cover, a wind barb gives direction and quantized speed, and up to three corner numerals carry temperature, dew point, and pressure. Five fields, one glyph, no legend — dense enough to tile a map, legible enough to read in a table cell. ```tsx <StationGlyph station="KSFO" cloud="0.75" wind="{ direction: 225, magnitude: 15 }" temp="16" dewpoint="9" pressure="1013" size="48" /> ``` ## Install [#install] ```tsx import { StationGlyph } from "@microcharts/react/station-glyph"; <StationGlyph station="KSFO" cloud={0.75} wind={{ direction: 225, magnitude: 15 }} temp={16} dewpoint={9} pressure={1013} /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a dense weather station model, or any multi-field reading that must fit one cell. * **Avoid for** — a single value (Delta) or a trend over time (Sparkline). ## Variants [#variants] ```tsx `"> <StationGlyph station="KJFK" cloud="1" wind="{ direction: 300, magnitude: 45 }" temp="4" dewpoint="2" pressure="988" size="48" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <StationGlyph station="STN" cloud="0.3" wind="{ direction: 0, magnitude: 0 }" size="44" /> ``` ```tsx `"> <StationGlyph cloud="0.4" size="44" /> ``` ```tsx `"> <StationGlyph size="44" /> ``` ```tsx `" > <StationGlyph station="EDDF" cloud="0.6" wind="{ direction: 90, magnitude: 22 }" temp="-3" dewpoint="-9" pressure="1024" format="{ maximumFractionDigits: 0 }" locale="de-DE" size="48" /> ``` `format`/`locale` flow through every corner numeral (temp, dew point, pressure) and the wind speed and numerals named in the accessible summary — one formatter, one locale, no per-field overrides. ## Why this default [#why-this-default] Each field rides its own channel, so nothing is inferred from a shared one: sky cover is disc area, wind is the barb (direction as angle, speed quantized into barbs so the per-barb quantum is honest), and the numerals are placed where a forecaster expects them. Wind speed is quantized rather than drawn to scale for the same reason WindBarb quantizes it — a barb count reads exactly, a tiny length does not. Absent fields simply don't render — no barb, no numeral, and no stop for the keyboard. The one field with no "absent" state is the disc itself: omitting `cloud` looks and reads exactly like a clear sky. ## Accessibility [#accessibility] The accessible name is the whole observation — **"KJFK, wind northwest 45; sky overcast, 4° / 2°, 988."** The interactive entry roves the *present* fields with ←/→ so a screen-reader user can step through station, wind, sky, temperature, dew point, and pressure one at a time — an omitted prop is not a stop — and Escape clears the focus back to the whole-observation reading. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `cloud` | `number` | Sky cover 0–1; fills the disc. | | `wind` | `{ direction, magnitude }` | Barb direction + speed. | | `step` | `number` | Wind-barb quantum — each full barb (default 10). | | `temp` | `number` | Upper-left numeral. | | `dewpoint` | `number` | Lower-left numeral. | | `pressure` | `number` | Upper-right numeral. | | `station` | `string` | Top-left identifier. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # StatusDot (/docs/charts/status-dot) StatusDot answers "what state is this thing in right now?". Every state pairs a distinct silhouette with a semantic color — filled circle, triangle, diamond, hollow ring, half-filled circle — so two states can never collapse into the same mark for the 1-in-12 colorblind readers a colored disc fails. ```tsx <span className="text-lg"> {"The API is "} <StatusDot status="ok" title="API" style="{ width: "0.6em", height: "0.6em" }" /> {" operational."} </span> ``` ## Install [#install] ```tsx import { StatusDot } from "@microcharts/react/status-dot"; <StatusDot status="ok" title="API" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — service lists, inline state in a sentence, monitoring rows. * **Avoid for** — quantities, trends, or vocabularies past \~6 states (marks stop being memorable). ## The state contract [#the-state-contract] | status | glyph | token | | ------- | ------------------ | --------------- | | `ok` | filled circle | `--mc-positive` | | `warn` | triangle | `--mc-cat-1` | | `error` | diamond | `--mc-negative` | | `off` | hollow ring | `--mc-neutral` | | `busy` | half-filled circle | `--mc-accent` | The pairing is a contract: `color` recolors a state but never reshapes it, and a theme must never let two states share a silhouette. ## Variants [#variants] ```tsx `" > <StatusDot status="ok" title="Live" style="{ width: 18, height: 18 }" /> ``` ```tsx `" > <StatusDot status="degraded" states="{ degraded: { glyph: "triangle", token: "--mc-cat-1", label: "degraded" } }" title="Search" style="{ width: 18, height: 18 }" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <StatusDot status="degraded" title="Unknown key" style="{ width: 18, height: 18 }" /> ``` ## Why this default [#why-this-default] Shape+color pairing beats a colored disc: the five silhouettes stay distinct in grayscale, print, and forced-colors, where color-only status dots all become the same gray circle. An unknown status key renders the `off` ring with a dev warning — never a plausible-looking wrong state. ## Accessibility [#accessibility] The accessible name is the state's label — **"Status: ok."** — composed with your `title` ("API. Status: ok."). The interactive entry announces state changes through a polite live region and stays quiet on mount. `pulse` is a CSS halo that disappears entirely under `prefers-reduced-motion`. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `status` (required) | `string` | Built-in ok \| warn \| error \| off \| busy, or a key of states. | | `pulse` | `boolean` | Live-now halo (reduced-motion-gated). | | `states` | `Record<string, { glyph; token; label }>` | Extend the vocabulary; the shape+color pairing is preserved. | | `color` | `string` | Recolors the active state; never reshapes it. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # StreakSpark (/docs/charts/streak-spark) StreakSpark answers "how long is the current run, and how does it compare to the record?". A sequence of pass/fail outcomes collapses into **runs** — each run a bar whose width is its length on one shared scale. Streak runs sit low and translucent, breaks sit thin and saturated, and the **current** run is the loud accent bar at the right. The record streak wears a small triangle tick, so "are we near our best" reads without counting. ```tsx `" > <StreakSpark data="[1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 0, 0, 1, 1, 1]" label="both" title="Deploy streak" width="300" height="48" /> ``` ## Install [#install] ```tsx import { StreakSpark } from "@microcharts/react/streak-spark"; // 1 = passing build, 0 = failing build <StreakSpark data={[1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 0, 0, 1, 1, 1]} title="Deploy streak" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — pass/fail run histories, uptime and incident-free streaks, the current run against a record. * **Avoid for** — a continuous magnitude (SparkBar) or a single completion ratio (Progress). ## Variants [#variants] `data` accepts booleans, `0`/`1`, or any numbers (they pass on `> 0`, or on `>= threshold`). A `null` is a gap: it breaks the run and starts a fresh one. Everything else is a prop. ```tsx `" > <StreakSpark data="[1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 0, 0, 1, 1, 1]" label="both" title="Current and record" width="300" height="48" /> ``` ```tsx `" > <StreakSpark data="[0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0]" positive="down" label="both" title="Incident-free streak" width="300" height="48" /> ``` ```tsx = threshold — e.g. daily uptime %, target 99.5 <StreakSpark data={[99.9, 99.8, 99.6, 98.2, 99.7, 99.9, 99.6, 97.0, 99.8, 99.9]} threshold={99.5} label="both" />`" > <StreakSpark data="[99.9, 99.8, 99.6, 98.2, 99.7, 99.9, 99.6, 97.0, 99.8, 99.9]" threshold="99.5" label="both" title="Uptime streak" width="300" height="48" /> ``` ```tsx 1)} format={{ useGrouping: true }} locale="de-DE" />`" > <StreakSpark data="Array.from({ length: 1204 }, () => 1)" format="{ useGrouping: true }" locale="de-DE" label="current" title="Localized run length" width="220" height="48" /> ``` With a `locale`, the count label and the accessible summary follow that locale's own grouping — a 1,204-build streak reads **"1.204"** in German. The outcome words come from `strings`, so the whole summary localizes together. ## Edge cases [#edge-cases] ```tsx `"> <StreakSpark data="[1]" title="One build" width="160" height="24" /> ``` A lone outcome is one current run of length 1, and it is trivially its own record — the summary reads **"Current run 1 passing, unbroken."** ```tsx `"> <StreakSpark data="[0, 0, 0, 0, 0]" title="Rough week" width="200" height="24" /> ``` When nothing passes there is no completed streak: the strip is one saturated break run, no triangle tick, and the summary reads **"Current run 5 failing; no completed streak."** ## Why this default [#why-this-default] Runs, not per-outcome ticks, because the decision is about *length* — "how long have we held" and "how does that compare to our best". Width encodes run length on one shared scale, so a wide bar is a genuinely long run and the eye compares them honestly. Height and opacity encode run *type* (streak, break, current) — never magnitude — so the ribbon never implies a size it doesn't have. The record tick and the accented current bar answer the two questions the raw list can't, at a glance. ## Accessibility [#accessibility] The accessible name states the current run, the record, and how often the streak broke — **"Current run 3 passing; record 9; broke 2 times."** The interactive entry roves runs with ← →, announcing each run's length, outcome, and whether it is the record (**"Run 3 of 5: 4 passing."**). Direction is carried by height, opacity, and color together, never color alone. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(boolean \| number \| null)[]` | Outcomes; null is a gap that breaks the run. Numbers pass on > 0. | | `positive` | `"up" \| "down"` | Which outcome is the streak: pass (up) or fail (down). | | `threshold` | `number` | With numeric data, values ≥ threshold pass. | | `label` | `"current" \| "both" \| "none"` | Count labels: the current run, the record too, or neither. | | `title` | `string` | Accessible name; joins the auto summary. | | `summary` | `string \| false` | Override or disable the auto summary. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # TallyMarks (/docs/charts/tally-marks) TallyMarks answers "how many?" the way a human actually counts — in four-and-strike clusters of five. The count reads back exactly: no scale to calibrate, no color to decode. Past `total` the marks stop growing and a `+N` numeral tells the truth, so a cell never blows out its width. Marks are never resized to fit — width grows with the count until the cap, then the numeral takes over. ```tsx <TallyMarks value="23" title="Signatures" height="20" /> ``` ## Install [#install] ```tsx import { TallyMarks } from "@microcharts/react/tally-marks"; <TallyMarks value={23} title="Signatures" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a small running count in a sentence or cell, a live event or score counter, or an editorial hand-tallied context. * **Avoid for** — large magnitudes (MiniBar), trends over time (Sparkline), or proportions (Progress). ## Variants [#variants] ```tsx <TallyMarks value={38} total={20} />`" > <span className="inline-flex gap-4 items-center"> <TallyMarks value="17" pen="drawn" height="20" /> <TallyMarks value="38" total="20" height="20" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <TallyMarks value="0" height="20" /> ``` ```tsx `"> <TallyMarks value="-5" height="20" /> ``` ```tsx `"> <TallyMarks value="5000" total="5000" height="20" /> ``` ## Why this default [#why-this-default] The ruled pen is the default because product tables want precision first — evenly ruled strokes count back fastest. The `drawn` pen adds a seeded, deterministic jitter (same count always renders identically, on the server and after hydration) for the editorial voice, and it only perturbs how each stroke is drawn — the count is never touched. Past `total`, the default `overflow="numeral"` appends a `+N` so the true total survives even when the marks can't; `overflow="clamp"` suppresses the numeral for dense columns, and the accessible name still carries the exact count. ## Accessibility [#accessibility] The accessible name is the exact count — **"17 counted."** — always the true value, even when the marks overflow to a `+N` numeral or clamp. The interactive entry announces the new total through a polite live region on change and draws newly added marks in with a brief, reduced-motion-gated sweep. A count has no sub-parts, so focus reads the summary and there is no cursor to move. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The count. Floored; negatives clamp to 0. | | `total` | `number` | Marks drawn before overflow (default 25). | | `overflow` | `"numeral" \| "clamp"` | numeral appends +N; clamp stops drawing. The summary always keeps the true count. | | `pen` | `"ruled" \| "drawn"` | Hand-drawn jitter for editorial contexts. | 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](/docs/quickstart#the-shared-grammar). # TapeGauge (/docs/charts/tape-gauge) TapeGauge answers "what is it now, is that OK, and where is it heading?" for a single live reading — airspeed, throughput, temperature, queue depth. The scale scrolls past a fixed center pointer, so the value stays parked where your eye already is; semantic zones mark the safe, caution, and danger bands; and a stack of chevrons encodes the rate of change as a channel entirely separate from the level. It is the aviation primary-flight-display tape, shrunk to a word. ```tsx <TapeGauge value="142" rate="1" zones="[ { from: 100, to: 130, tone: "pos" }, { from: 130, to: 150, tone: "warn" }, { from: 150, to: 200, tone: "neg" }, ]" span="60" title="Airspeed" width="46" height="72" /> ``` ## Install [#install] ```tsx import { TapeGauge } from "@microcharts/react/tape-gauge"; <TapeGauge value={142} rate={1} zones={zones} span={60} title="Airspeed" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a live changing reading with a safe/caution band; value plus trend at a glance. * **Avoid for** — a history you want to scan (Sparkline) or a single static number (Delta). ## Variants [#variants] ```tsx // label="none" drops the in-chart readout for an external number <TapeGauge value={142} rate={1} zones={zones} span={60} label="none" />`" > <span className="inline-flex items-end gap-6"> <TapeGauge value="142" rate="-1" zones="[ { from: 100, to: 130, tone: "pos" }, { from: 130, to: 150, tone: "warn" }, { from: 150, to: 200, tone: "neg" }, ]" span="60" orientation="horizontal" title="Airspeed" width="160" height="30" /> <TapeGauge value="142" rate="1" zones="[ { from: 100, to: 130, tone: "pos" }, { from: 130, to: 150, tone: "warn" }, { from: 150, to: 200, tone: "neg" }, ]" span="60" label="none" title="Airspeed" width="30" height="44" /> </span> ``` ```tsx `" > <TapeGauge value="14200" format="{ maximumFractionDigits: 0 }" locale="de-DE" title="Localized reading" width="46" height="68" /> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, both the in-gauge readout and the accessible summary follow that locale's own grouping ("14.200" in German, not "14,200"). ## Edge cases [#edge-cases] ```tsx `" > <TapeGauge value="NaN" title="Sensor offline" width="46" height="68" /> ``` ```tsx `" > <TapeGauge value="142" rate="1" span="40" title="Airspeed, unzoned" width="46" height="68" /> ``` ## Why this default [#why-this-default] The value is pinned at the pointer and the scale moves instead, because on a live instrument the one thing you never want to hunt for is the current reading. Rate lives on its own channel — chevrons, not position — so a fast climb and a high value are never confused for one another, the failure mode that sinks a naïve gauge. The visible span is fixed while the value updates, so a jump reads as motion of the scale rather than a silent rescale that hides how far it moved. ## Accessibility [#accessibility] The accessible name states the level, the trend word, and the containing zone — **"Now 142, rising; in the 130–150 zone."** The interactive entry re-announces the reading through a polite live region, throttled so a rapidly changing value never floods a screen reader, and focus reads the full summary on demand. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The current level; parked at the pointer. | | `rate` | `number` | Signed units/tick; drives the chevrons. | | `zones` | `{ from, to, tone }[]` | Semantic bands on the scale. | | `span` | `number` | Visible scale extent; fixed while live. | | `rateTiers` | `[number, number]` | Thresholds for 1 and 2 chevrons (default [span/60, span/15]). | | `orientation` | `"vertical" \| "horizontal"` | Tape direction (default vertical). | | `announceEvery` | `number` | (interactive) Minimum ms between live-region announcements as the value streams (default 5000). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Thermometer (/docs/charts/thermometer) Thermometer answers "where does this value sit on a calibrated range, and how close to the goal?" A column fills a ticked tube; the ticks calibrate the read, which is what buys the precision. The fill always anchors at the bottom of the range — never re-zeroed, never log — and an optional target line crosses the tube to mark the goal. The bulb is instrument chrome (always full); it is not data, so its area means nothing. ```tsx <Thermometer value="72" target="80" title="Fundraiser" height="56" /> ``` ## Install [#install] ```tsx import { Thermometer } from "@microcharts/react/thermometer"; <Thermometer value={72} target={80} title="Fundraiser" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a fundraising or goal-progress read, a capacity or utilization gauge in a cell, or any value against a stated range. * **Avoid for** — trends (Sparkline), proportions of a whole (SegmentedBar), or many series. ## Variants [#variants] ```tsx <Thermometer value={72} domain={[32, 100]} ticks={[32, 50, 68, 86, 100]} />`" > <span className="inline-flex gap-6 items-center"> <Thermometer value="62" orientation="horizontal" bulb="false" width="110" /> <Thermometer value="72" domain="[32, 100]" ticks="[32, 50, 68, 86, 100]" height="60" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <Thermometer value="130" domain="[0, 100]" title="Overrun" height="48" /> ``` ```tsx `"> <Thermometer value="0" title="Empty" height="48" /> ``` ```tsx `" > <Thermometer value="7234" domain="[0, 10000]" target="8000" format="{ maximumFractionDigits: 0 }" locale="de-DE" label="value" title="Fundraiser" height="56" /> ``` The accessible summary's value, domain, and target all go through the same locale-aware formatter, so "7,234" becomes "7.234" in German grouping. ## Why this default [#why-this-default] Vertical with the bulb is the default because the instrument metaphor is the point — a filling tube reads as "toward the goal" instantly. Horizontal exists for table cells where a vertical tube cannot fit, and `bulb={false}` drops the reservoir when the metaphor runs too warm for the context. The `domain` defaults to `[0, 100]` because a calibrated instrument needs a stated range; auto-fitting would silently move the scale under the reader. A value beyond the domain clamps the fill but the accessible name always reports the true number — the reading is never silently clipped. ## Accessibility [#accessibility] The accessible name states the value on its scale — **"62 on a 0–100 scale."** — and appends the goal when a target is set. The interactive entry reveals the exact value on hover or focus, glides the fill to its new level with a reduced-motion-gated transition, and announces each change through a polite live region. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The reading. | | `target` | `number` | A goal tick across the tube. | | `domain` | `[number, number]` | The calibrated range (default [0, 100]). | | `ticks` | `number \| number[]` | Tick count or explicit values. | | `orientation` | `"vertical" \| "horizontal"` | Horizontal fits table cells. | | `bulb` | `boolean` | Draw the reservoir bulb (default true). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # TimeInRange (/docs/charts/time-in-range) TimeInRange answers "how much of the period was the metric inside its acceptable corridor — and which side did it miss on?". Zones sit in a fixed semantic order — below, in, above — so the strip is read by position first and color second. The in-range percent is the one number that matters. ```tsx <TimeInRange data="{ below: 9, in: 72, above: 19 }" title="Time in range" width="240" height="22" /> ``` ## Install [#install] ```tsx import { TimeInRange } from "@microcharts/react/time-in-range"; <TimeInRange data={{ below: 9, in: 72, above: 19 }} title="Time in range" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — SLO / uptime corridors, glucose-style time-in-range, thermal or budget bands. * **Avoid for** — ranking parts (SegmentedBar) or a single ratio (Progress). ## Variants [#variants] ```tsx `" > <TimeInRange data="{ severeBelow: 2, below: 7, in: 72, above: 15, severeAbove: 4 }" orientation="vertical" label="all" title="Vertical" width="28" height="130" /> ``` ```tsx `"> <TimeInRange data="{ severeBelow: 3, below: 8, in: 64, above: 18, severeAbove: 7 }" title="Severity tiers" width="240" height="22" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <TimeInRange data="{ below: 0, in: 0, above: 0 }" title="No readings yet" width="160" height="16" /> ``` ```tsx `" > <TimeInRange data="{ below: 3, in: 90, above: 7 }" label="all" title="Mostly in range" width="60" height="10" /> ``` ## Why this default [#why-this-default] Zone order is semantic and immutable — it is never sorted by magnitude, because the position of a miss (too low vs too high) is half the reading. Severity tiers are drawn with the same hue at greater ink weight, so the strip never relies on color alone. Percent labels round with largest-remainder rounding so they always sum to 100, and the summary reads the same integers as the label. ## Accessibility [#accessibility] The accessible name leads with the headline and then the misses — **"72% in range, 7% below, 15% above, 2% severe low, 4% severe high."** The interactive entry roves the zones; each announces its share (**"in range: 72%."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `TimeInRangeDatum` | Counts or fractions; normalized to 1. | | `orientation` | `"horizontal" \| "vertical"` | Vertical suits clinical columns and KPI cards. | | `label` | `"in" \| "all" \| "none"` | The in-range headline, a full audit, or clean. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # TokenConfidence (/docs/charts/token-confidence) TokenConfidence answers "which parts of this generated text should I double-check?". The text itself is the chart: confidence becomes a typographic underline beneath each token, in three discrete tiers — confident tokens get no mark at all, so reading stays primary and only the uncertain words draw the eye. ```tsx `" > <TokenConfidence data="[ { token: "The", confidence: 0.98 }, { token: " Treaty", confidence: 0.93 }, { token: " of", confidence: 0.99 }, { token: " Westphalia", confidence: 0.71 }, { token: " was", confidence: 0.96 }, { token: " signed", confidence: 0.9 }, { token: " in", confidence: 0.97 }, { token: " 1648", confidence: 0.44 }, { token: ", ending the Thirty", confidence: 0.63 }, { token: " Years' War", confidence: 0.85 }, { token: " over", confidence: 0.31 }, { token: " a decade", confidence: 0.38 }, { token: ".", confidence: 0.99 }, ]" title="Model answer" style="{ fontSize: "1.05rem" }" /> ``` ## Install [#install] ```tsx import { TokenConfidence } from "@microcharts/react/token-confidence"; <TokenConfidence data={tokens} title="Model answer" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — LLM answers in chat or transcripts, flagging text to review. * **Avoid for** — numeric confidence auditing (use CalibrationStrip) or a single score (Delta). ## Sizing [#sizing] The text is the chart, so it inherits the surrounding font size — there is no `width`/`height`. Set `style={{ fontSize }}` or let it flow inline with your prose. ## Variants [#variants] ```tsx `" > <TokenConfidence data="[ { token: "Likely", confidence: 0.92 }, { token: " Paris", confidence: 0.62 }, { token: ", maybe", confidence: 0.3 }, { token: " Lyon", confidence: 0.28 }, ]" style="{ fontSize: "1.05rem" }" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <TokenConfidence data="[ { token: "The", confidence: 0.95 }, { token: " answer", confidence: 0.99 }, { token: " is", confidence: 0.97 }, { token: " Paris", confidence: 0.9 }, ]" style="{ fontSize: "1.05rem" }" /> ``` Every token clears the `hi` threshold, so nothing is flagged — the sentence renders as plain, unmarked text. That absence of marks is the finding: nothing here needs a second look. ```tsx `"> <TokenConfidence data="[]" style="{ fontSize: "1.05rem" }" /> ``` An empty `data` array renders nothing and reports **"No tokens."** to assistive tech. ## Why this default [#why-this-default] The tiers are discrete — confident, unsure, guessing — never a continuous gradient, because people calibrate categorically: a smooth colour ramp reads as noise, but "double-check this word" reads instantly. Confident tokens carry no mark at all, and the two flagged tiers differ in **stroke style** as well as colour — unsure is a solid underline, guessing a dotted one — so the tier never depends on colour alone. For auditing exact probabilities, reach for [CalibrationStrip](/docs/charts/calibration-strip) instead. ## Accessibility [#accessibility] The accessible name is the tier tally — **"4 tokens: 1 confident, 1 unsure, 2 guessing."** The interactive entry gives each flagged token a roving tab stop; ←/→ move between them (skipping confident tokens), announcing each one's tier and confidence. ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ token, confidence }[]` | Tokens + confidences. | | `tiers` | `readonly [number, number]` | lo/hi thresholds — the only tuning. | | `show` | `"flagged" \| "all"` | All also hairlines confident tokens. | | `legend` | `boolean` | Appends the 1-line inline key. | 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](/docs/quickstart#the-shared-grammar). # TraceFold (/docs/charts/trace-fold) TraceFold answers "where did the latency go — which spans, at which depth, on the path that actually determined the total?". Each span is a rect placed by its start time, sized by its duration, and stacked by its nesting depth. The critical path — the chain of spans that bound the total — is accented and everything else muted, so the answer to "which spans mattered" is immediate. ```tsx \`\${Math.round(n)} ms\`} title="Request trace" />`" > <TraceFold data="[ { label: "request", start: 0, duration: 214, depth: 0 }, { label: "db.query", start: 10, duration: 86, depth: 1, parent: 0 }, { label: "auth", start: 0, duration: 8, depth: 1, parent: 0 }, { label: "render", start: 96, duration: 60, depth: 1, parent: 0 }, { label: "serialize", start: 156, duration: 40, depth: 1, parent: 0 }, { label: "index-scan", start: 12, duration: 70, depth: 2, parent: 1 }, { label: "decode", start: 82, duration: 12, depth: 2, parent: 1 }, { label: "log", start: 200, duration: 14, depth: 1, parent: 0 }, { label: "gc", start: 90, duration: 5, depth: 2, parent: 1 }, ]" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" title="Request trace" width="300" height="48" /> ``` ## Install [#install] ```tsx import { TraceFold } from "@microcharts/react/trace-fold"; <TraceFold data={spans} title="Request trace" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — request traces, flame charts, p95-exemplar latency breakdowns. * **Avoid for** — a single duration (Bullet) or a time series (Sparkline). ## Variants [#variants] ```tsx \`\${Math.round(n)} ms\`} />`" > <TraceFold data="[ { label: "request", start: 0, duration: 214, depth: 0 }, { label: "db.query", start: 10, duration: 86, depth: 1, parent: 0 }, { label: "render", start: 96, duration: 60, depth: 1, parent: 0 }, { label: "index-scan", start: 12, duration: 70, depth: 2, parent: 1 }, ]" emphasis="none" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" title="Structure" width="300" height="44" /> ``` ```tsx `" > <TraceFold data="[ { label: "request", start: 0, duration: 14868, depth: 0 }, { label: "db.query", start: 1200, duration: 9234, depth: 1, parent: 0 }, ]" format="{ style: "unit", unit: "millisecond", unitDisplay: "narrow", maximumFractionDigits: 0 }" locale="de-DE" title="Localized durations" width="220" height="32" /> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, the accessible summary's numbers follow that locale's own grouping and decimal marks ("14.868 ms" in German, not "14,868 ms"). In-rect text stays the plain span label either way; only the announced numbers are localized. ## Edge cases [#edge-cases] ```tsx `"> <TraceFold data="[{ label: "request", start: 0, duration: 42, depth: 0 }]" title="Single span" width="160" height="24" /> ``` ```tsx `" > <TraceFold data="[ { label: "request", start: 0, duration: 120, depth: 0 }, { label: "db.query", start: 10, duration: 70, depth: 1, parent: 0 }, { label: "index-scan", start: 12, duration: 40, depth: 2, parent: 1 }, ]" title="Squeezed" width="200" height="24" /> ``` ## Why this default [#why-this-default] Accenting the critical path because "which spans mattered" is the question a uniform flame strip doesn't answer — the eye goes straight to the chain that set the total. Widths are durations on one linear shared time scale, never per-row normalized, so a wide span is genuinely a slow span. The only documented width distortion is a one-unit floor for zero-duration spans, and the critical-path walk is deterministic (ties resolve to the earliest start). ## Accessibility [#accessibility] The accessible name names the biggest span and its path status — **"4 spans over 214 ms; longest db.query (86 ms) on the critical path."** The interactive entry roves spans within a depth with ←/→ and between depths with ↑/↓, announcing each span's duration, share of the total, depth, and whether it is on the critical path. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `Span[]` | Flat span list; parent = index. | | `emphasis` | `"critical" \| "none"` | Mute non-critical spans, or uniform. | | `labels` | `boolean` | Width-gated in-rect labels. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # TreeRings (/docs/charts/tree-rings) TreeRings answers "how did growth accumulate, period over period?" like the rings of a tree: the oldest period is at the centre and each new period adds a ring outward, whose **thickness** is that period's value. The channel is thickness, not area — equal thickness at a larger radius spans more area (the ring illusion), so read the thicknesses, not the wedges; exact per-period reads steer to `SparkBar`. ```tsx <TreeRings data="[8, 12, 10, 18, 22, 15, 20, 14]" label="last" unit="years" periodWord="year" title="Account age" size="40" /> ``` ## Install [#install] ```tsx import { TreeRings } from "@microcharts/react/tree-rings"; <TreeRings data={years} unit="years" periodWord="year" title="Account age" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — account or company age at a glance, a cohort-age marker in a table cell, or a per-period growth story in a KPI card. * **Avoid for** — exact per-period reads (SparkBar), many periods (over twenty-four), or non-cumulative series. ## Variants [#variants] ```tsx <TreeRings data={years} total={200} />`" > <span className="inline-flex gap-6 items-center"> <TreeRings data="[8, 12, 10, 18, 22, 15, 20, 14]" rings="fill" size="44" /> <TreeRings data="[8, 12, 10, 18, 22, 15, 20, 14]" total="200" size="44" /> </span> ``` ```tsx `"> <TreeRings data="[820, 1240, 990, 1810]" label="last" locale="de-DE" title="Localized growth" size="44" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <TreeRings data="[8, 12, 0, 18, 22]" title="A flat quarter" size="44" /> ``` ```tsx `"> <TreeRings data="[]" title="New account" size="44" /> ``` ## Why this default [#why-this-default] Stroke rings are the default because at twenty-four pixels hairlines keep the disc quiet and let the accent ring — the current period, drawn 1.5× heavier in the accent color (weight and color, never color alone) — stay loud. The channel is radial **thickness**, and the docs say so explicitly, because equal thickness at a larger radius spans more area. TreeRings never enforces a minimum visual thickness: a near-zero period looks near-zero, and a zero-value period collapses its two boundaries onto each other. Pass `total` for the cohort-age story — the disc then fills only Σdata/total of the radius, so a young account reads as part-grown. ## Accessibility [#accessibility] The accessible name summarizes the growth — **"8 periods; latest 14, biggest 22 in period 5."** The interactive entry steps the rings from the centre out with ←/→ (or hover), announcing each period as "Year 5: 22." The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Per-period growth, oldest first. | | `highlight` | `"last" \| "none" \| number` | Which period's ring to pick out. | | `total` | `number` | Expected lifetime Σ — the disc fills only Σdata/total. | | `rings` | `"stroke" \| "fill"` | Boundary rings (default) or filled annuli. | | `periodWord` | `string` | Singular period noun for the summary (default "period"). | | `unit` | `string` | Plural period noun for the summary (default "periods"). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # TrendArrow (/docs/charts/trend-arrow) TrendArrow answers "which way is this moving?" at glyph size. The shape *is* the direction — up, down, or a flat bar — and color only reinforces it, so the read survives grayscale, print, and forced-colors. When the magnitude matters, reach for [Delta](/docs/charts/delta) instead. ```tsx `" > <span className="text-lg"> {"Latency "} <TrendArrow value="-0.08" positive="down" format="{ style: "percent", maximumFractionDigits: 0 }" title="Latency vs last week" style="{ width: "1em", height: "1em" }" /> {" improved again this week."} </span> ``` ## Install [#install] ```tsx import { TrendArrow } from "@microcharts/react/trend-arrow"; <TrendArrow value={-0.08} positive="down" title="Latency vs last week" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — table direction columns, dense dashboards, inline movement cues. * **Avoid for** — exact magnitudes (Delta) or series shape (Sparkline). ## Sizing [#sizing] The glyph is a fixed 16-unit box that scales like an image — size it with CSS. With `showValue` the viewBox widens to reserve a gutter for the number, so text never paints outside the chart. ## Variants [#variants] Three glyph weights for three densities, an honest noise floor, and the number when the glyph alone is too terse. ```tsx <TrendArrow value={1} glyph="triangle" /> <TrendArrow value={1} glyph="chevron" />`" > <span className="inline-flex items-center gap-3"> <TrendArrow value="1" glyph="arrow" title="Arrow" style="{ width: 20, height: 20 }" /> <TrendArrow value="1" glyph="triangle" title="Triangle" style="{ width: 20, height: 20 }" /> <TrendArrow value="1" glyph="chevron" title="Chevron" style="{ width: 20, height: 20 }" /> </span> ``` ```tsx `" > <span className="inline-flex items-center gap-3"> <TrendArrow value="0.01" flatBand="0.02" title="Within noise" style="{ width: 20, height: 20 }" /> </span> ``` ```tsx `"> <TrendArrow value="0.12" format="{ style: "percent", maximumFractionDigits: 0 }" title="Weekly change" style="{ height: 22 }" /> ``` ```tsx `"> <TrendArrow value="-0.08" positive="down" title="Latency" style="{ width: 20, height: 20 }" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <TrendArrow value="0" title="No change" style="{ height: 20 }" /> ``` ```tsx `"> <TrendArrow value="Number.NaN" title="Invalid" style="{ height: 20 }" /> ``` ```tsx `"> <TrendArrow value="12483" format="{ maximumFractionDigits: 0 }" locale="de-DE" title="Signups" style="{ height: 22 }" /> ``` `format`/`locale` reach `showValue`'s number and the accessible summary's magnitude together — "12,483" becomes "12.483" in German grouping. ## Why this default [#why-this-default] The arrow (shaft + head) stays legible at 8 px and in forced-colors where lighter marks blur; the glyph never scales with magnitude — an arrow twice as long would be a lie at this precision. `flatBand` exists so tiny wiggles don't read as movement: declare your noise floor instead of letting every ±0.1% look like a trend. ## Accessibility [#accessibility] The default accessible name is the factual direction — **"Up 12%."**, **"No change."** within the flat band, **"No data."** for non-finite input. `positive="down"` flips only the color, never the glyph or the words. The interactive entry announces direction changes through a polite live region and pulses the glyph (gated on reduced motion). This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | Signed change; sign → direction, magnitude only via showValue/summary. | | `flatBand` | `number` | Noise floor: \|value\| ≤ flatBand renders the flat glyph. | | `glyph` | `"arrow" \| "triangle" \| "chevron"` | Mark weight: default legibility, dense cells, inline text. | | `showValue` | `boolean` | Append the formatted value in a right gutter. | | `positive` | `"up" \| "down"` | Which direction is good (colors only, never the glyph). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # VolumeProfile (/docs/charts/volume-profile) VolumeProfile answers "at which *level* did activity concentrate — not when?". It is a histogram turned perpendicular to the usual trend axis: the level runs vertically and bars extend horizontally by the mass of activity at each level. The modal level — the point of control, or POC — is accented, and the value area (the levels holding most of the activity) is shaded. ```tsx `" > <VolumeProfile data="[ { level: 134, weight: 3 }, { level: 136, weight: 6 }, { level: 138, weight: 11 }, { level: 140, weight: 18 }, { level: 142, weight: 26 }, { level: 144, weight: 20 }, { level: 146, weight: 12 }, { level: 148, weight: 7 }, { level: 150, weight: 4 }, ]" title="Volume by price" width="120" height="90" /> ``` ## Install [#install] ```tsx import { VolumeProfile } from "@microcharts/react/volume-profile"; <VolumeProfile data={profile} title="Volume by price" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — volume-at-price, level-of-activity distributions, load by tier. * **Avoid for** — a time series (Sparkline) or when the timing is what matters. ## Variants [#variants] ```tsx `" > <VolumeProfile data="[ { level: 138, weight: 11 }, { level: 140, weight: 18 }, { level: 142, weight: 26 }, { level: 144, weight: 20 }, { level: 146, weight: 12 }, ]" align="right" title="Right side" width="120" height="70" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <VolumeProfile data="[142, 142, 142, 142]" title="Single level" width="80" height="40" /> ``` ```tsx `" > <VolumeProfile data="[]" title="Empty" width="80" height="40" /> ``` ## Why this default [#why-this-default] A perpendicular histogram because "where" is a different question from "when", and no time-axis chart can answer it. The value area is a stated convention — `valueArea` defaults to `0.7`, and the fraction is stated in the summary — not an implied confidence interval. The modal bin is the only accented mark, because "where did activity pile up" is the one question the shape is built to answer. ## Accessibility [#accessibility] The accessible name states where activity concentrates — **"Activity concentrates at 142.33 (POC); 70% within 140.33–145.67."** (the right-aligned demo's 5-level profile, default 12 bins). An even distribution reads **"Activity is evenly spread."** The interactive entry roves the levels with ↑/↓, announcing each level's share of activity and flagging the POC. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ level, weight }[] \| number[]` | Activity mass per level, or raw levels. | | `valueArea` | `number` | Mass fraction of the shaded value area (0.7). | | `align` | `"left" \| "right"` | Which way bars grow. | | `label` | `"poc" \| "none"` | The POC level beside the accent bar. | | `bins` | `number` | Number of histogram bins (default 12). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Waterfall (/docs/charts/waterfall) Waterfall answers "how did the deltas compose into the total?" — the P\&L bridge, in a cell. Sign is encoded by vertical direction from the running level AND by valence color, never color alone. ```tsx <Waterfall data="[ { label: "Product", value: 42 }, { label: "Services", value: 18 }, { label: "Refunds", value: -12 }, { label: "Opex", value: -26 }, { label: "FX", value: 5 }, ]" open="60" title="Net income bridge" width="220" height="30" /> ``` ## Install [#install] ```tsx import { Waterfall } from "@microcharts/react/waterfall"; <Waterfall data={steps} open={60} title="Net income bridge" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — P\&L bridges in table cells, net-change decomposition in KPI cards. * **Avoid for** — unordered category comparison (MiniBar), or more than \~8 steps. ## Variants [#variants] ```tsx <Waterfall data={steps} open={60} totalBar={false} />`" > <span className="inline-flex flex-col gap-3"> <Waterfall data="[ { label: "Product", value: 42 }, { label: "Services", value: 18 }, { label: "Refunds", value: -12 }, { label: "Opex", value: -26 }, { label: "FX", value: 5 }, ]" open="60" title="Net income bridge" width="240" height="30" /> <Waterfall data="[ { label: "Product", value: 42 }, { label: "Services", value: 18 }, { label: "Refunds", value: -12 }, { label: "Opex", value: -26 }, { label: "FX", value: 5 }, ]" open="60" totalBar="false" title="Steps only" width="220" height="30" /> </span> ``` ```tsx `" > <Waterfall data="[ { label: "Cloud", value: -8 }, { label: "Headcount", value: 14 }, { label: "Vendors", value: -5 }, { label: "Travel", value: -3 }, ]" open="40" positive="down" title="Cost bridge" width="220" height="30" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <Waterfall data="[ { label: "Q1", value: -20 }, { label: "Q2", value: -35 }, { label: "Q3", value: -10 }, ]" open="0" title="All losses" width="180" height="30" /> ``` ```tsx `" > <Waterfall data="[ { label: "Product", value: 30 }, { label: "Flat", value: 0 }, { label: "Refunds", value: -12 }, ]" open="50" title="Zero step" width="180" height="30" /> ``` ## Why this default [#why-this-default] The zero-anchored total bar stays on by default: a waterfall without a grounded total is unverifiable — floating bars alone can't be checked against reality. Hairline connectors carry the running level between steps without adding ink. ## Accessibility [#accessibility] The accessible name states the endpoints and the split — **"From 60 to 87 over 5 steps: +65 gains, −38 losses."** The interactive entry steps through the bridge (**"Refunds: −12, running 108."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value }[]` | Signed deltas in order. | | `open` | `number` | Opening level (prior-period close). | | `totalBar` | `boolean` | Zero-anchored closing total bar (default on). | | `positive` | `"up" \| "down"` | "down" = decreases are good (cost breakdowns). | | `label` | `"none" \| "delta"` | "delta" (default) prints each step's signed value in a band below the plot; the biggest movers win when labels would collide. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Waveform (/docs/charts/waveform) Waveform answers "what is the shape of a high-frequency signal — where are its spikes and silences — at word width?". It compresses with max-per-bucket, never a mean, so a single spike survives the squeeze to a sparkline width. The peak is disclosed in the accessible summary. ```tsx (i === 126 ? 0.82 : Math.sin(i / 3) * 0.15 + Math.sin(i / 11) * 0.35) * (1 - Math.abs(i - 100) / 260), )} title="Voice memo" />`" > <Waveform data="Array.from({ length: 200 }, (_, i) => (i === 126 ? 0.82 : Math.sin(i / 3) * 0.15 + Math.sin(i / 11) * 0.35) * (1 - Math.abs(i - 100) / 260))" progress="0.63" title="Voice memo" width="300" height="30" /> ``` ## Install [#install] ```tsx import { Waveform } from "@microcharts/react/waveform"; <Waveform data={samples} title="Voice memo" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — voice-memo / audio scrubbers, high-frequency log or request volume. * **Avoid for** — exact values (Sparkline) or categorical state (Hypnogram). ## Variants [#variants] ```tsx Math.sin(i / 3) * 0.4 * (1 - Math.abs(i - 100) / 220))} mode="envelope" />`" > <Waveform data="Array.from({ length: 200 }, (_, i) => Math.sin(i / 3) * 0.4 * (1 - Math.abs(i - 100) / 220))" mode="envelope" title="Envelope" width="280" height="30" /> ``` ```tsx `"> <Waveform data="[0.2, 0.5, 0.82, 0.4, 0.1]" locale="de-DE" title="Localized peak" width="90" height="22" /> ``` With a `locale`, the announced peak follows that locale's own decimal mark — "0,82" in German, not "0.82". ## Edge cases [#edge-cases] ```tsx `"> <Waveform data="[0.6]" title="One sample" width="60" height="20" /> ``` ```tsx `"> <Waveform data="[0, 0, 0, 0, 0, 0, 0, 0]" title="Silent" width="100" height="20" /> ``` A single sample renders as one bucket, top-to-bottom. All-zero data renders every bucket at the shared 0.4-unit "silent" tick height, and the accessible summary says **"Silent."** rather than reporting a zero peak. A `null` in the data behaves the same as a true zero for any bucket where it's the only sample — `maxPerBucket` skips non-finite values when picking the bucket's peak, and a bucket with nothing finite in it falls back to that same silence tick, so a genuine gap and real silence render identically here (unlike Sparkline's line break). ## Why this default [#why-this-default] Bars with max-per-bucket are the only compression that can't hide an incident — averaging a bucket would erase the very spike someone is looking for. The auto domain is symmetric ±max|data|, which reads shape honestly and discloses the peak in the summary; for absolute loudness comparison across rows, pass an explicit shared `domain` so quiet data is never silently rescaled to look loud. ## Accessibility [#accessibility] The accessible name discloses the peak — **"Peak 0.398 at 50% through 200 samples."** Pure silence reads **"Silent."** rather than blank. The interactive entry roves the buckets, announcing each bucket's position and peak amplitude. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Amplitude samples; negatives allowed. | | `progress` | `number` | 0–1 played fraction; left buckets tint accent. | | `mode` | `"bars" \| "envelope"` | Envelope draws the min/max area. | | `mirror` | `boolean` | Mirror around center; false for magnitude-only. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # WinProbWorm (/docs/charts/win-prob-worm) WinProbWorm answers "who's winning, and when did the lead flip?". It plots one win-probability series on a **fixed 0–100 axis that is never truncated** — the honesty rule for a probability — and splits the worm at the 50% line: while your side leads the line reads accent, when it trails it reads neutral, and a dot marks each lead change. Because a win-probability curve is a modelled read, the summary always says so, "per the supplied model". ```tsx <WinProbWorm data="[50, 48, 45, 52, 60, 58, 42, 38, 55, 68, 82, 90, 88, 94, 98]" sides="["home", "away"]" title="Win probability" width="220" height="28" /> ``` ## Install [#install] ```tsx import { WinProbWorm } from "@microcharts/react/win-prob-worm"; <WinProbWorm data={[50, 48, 45, 52, 60, 58, 42, 38, 55, 68, 82, 90, 88, 94, 98]} sides={["home", "away"]} title="Win probability" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — live win or election probability where the lead flips, a modelled forecast whose crossings are the story, and any 0–100 probability you must not truncate. * **Avoid for** — a raw score or margin (Sparkline), or a value that isn't a bounded 0–100 probability. ## Variants [#variants] ```tsx <WinProbWorm data={[50, 53, 49, 52, 48, 51, 47, 50, 46, 49, 45, 48, 52]} sides={["home", "away"]} />`" > <span className="inline-flex gap-4 items-center"> <WinProbWorm data="[50, 58, 66, 74, 80, 86, 90, 93, 96, 98, 99]" sides="["home", "away"]" width="160" height="24" /> <WinProbWorm data="[50, 53, 49, 52, 48, 51, 47, 50, 46, 49, 45, 48, 52]" sides="["home", "away"]" width="160" height="24" /> </span> ``` At a taller size the biggest single momentum swing gets a hair connector and a signed delta; drop it with `markSwing={false}`, and drop the endpoint probability with `label="none"`. ```tsx `" > <WinProbWorm data="[50, 48, 45, 52, 60, 58, 42, 38, 55, 68, 82, 90, 88, 94, 98]" sides="["home", "away"]" markSwing="false" label="none" width="220" height="28" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <WinProbWorm data="[50, 55.5, 61.2, 58.4, 63.5]" sides="["Ja", "Nein"]" format="{ minimumFractionDigits: 1 }" locale="de-DE" title="Modelled probability" width="180" height="26" /> ``` ```tsx `" > <WinProbWorm data="[50, 50, 50, 50, 50]" sides="["home", "away"]" title="Tied" width="160" height="24" /> ``` ```tsx `"> <WinProbWorm data="[72]" sides="["home", "away"]" title="One reading" width="110" height="24" /> ``` With a `format` and `locale`, the endpoint label and the summary format their numbers in that locale's own decimal mark — `[50, 55.5, 61.2, 58.4, 63.5]` in `de-DE` ends at **"63,5%"**. Values outside 0–100 are clamped to the axis and dev-warn — a probability cannot exceed 100. A constant series has no crossing and no swing: an all-50 series reads "even… throughout", any other constant reads "…holds X% throughout". A `null` breaks the worm into disconnected runs the way a gap should; a single point has no line to draw, so it renders just the endpoint dot and its label; `data={[]}` renders the frame with the "no data" summary. ## Why this default [#why-this-default] The fixed 0–100 axis is the whole point: a win probability that truncated its own scale would exaggerate a lead, so the axis never moves and a 2-point edge always looks like a 2-point edge. The 50% split does the reasoning for the reader — accent while your side leads, neutral while it trails, a dot at each flip — so "who's ahead, and did it ever change?" is answered before the second glance. The endpoint carries the current number, and the biggest momentum swing is marked only when there's room for it. The worm is a modelled read, never a fact, so its accessible name is framed "per the supplied model" and the chart never editorializes the forecast. ## Accessibility [#accessibility] The accessible name states the current leader, their probability, the number of lead changes, and the biggest momentum swing — **"Per the supplied model, home leads at 98%; 3 lead changes, biggest swing +17 at point 8."** — or, for a constant series, "Per the supplied model, even at 50% throughout." The interactive entry roves the points with ←/→ (Home/End jump to the ends), each announcing the leader and probability at that point, with a live readout chip. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | A single win-probability series, clamped to 0–100. | | `sides` | `[string, string]` | Names for the two sides — [>50, <50]. Default ["A", "B"]. | | `label` | `"last" \| "none"` | Print the current leader's probability at the endpoint (default "last"). | | `markSwing` | `boolean` | Mark the biggest momentum swing (default true; seat-gated). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # WindBarb (/docs/charts/wind-barb) WindBarb answers "which way is it flowing and roughly how hard — in one character?". The shaft points along the bearing and the barbs count the magnitude: a half barb, a full barb, and a pennant are fixed quanta, so the glyph reads at a glance without a scale. Quantization is the honesty here, not a limitation — the per-barb quantum is stated next to every example. ```tsx <WindBarb direction="225" magnitude="32" step="10" label="value" title="Wind" size="64" /> ``` ## Install [#install] ```tsx import { WindBarb } from "@microcharts/react/wind-barb"; <WindBarb direction={225} magnitude={32} step={10} title="Wind" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## Reading the barb [#reading-the-barb] WindBarb has no interactive mode — a single glyph carries the whole reading, so its accessible name is the full sentence. This gallery is the read-back key: each full barb is one `step`, a half barb is half a `step`, and a pennant is five. ```tsx `"> <span style="{ display: "inline-flex", gap: "0.5rem", flexWrap: "wrap", justifyContent: "center" }"> <WindBarb direction="0" magnitude="35" title="0°" size="40" summary="false" /> <WindBarb direction="45" magnitude="35" title="45°" size="40" summary="false" /> <WindBarb direction="90" magnitude="35" title="90°" size="40" summary="false" /> <WindBarb direction="135" magnitude="35" title="135°" size="40" summary="false" /> <WindBarb direction="180" magnitude="35" title="180°" size="40" summary="false" /> <WindBarb direction="225" magnitude="35" title="225°" size="40" summary="false" /> <WindBarb direction="270" magnitude="35" title="270°" size="40" summary="false" /> <WindBarb direction="315" magnitude="35" title="315°" size="40" summary="false" /> </span> ``` ```tsx `"> <span style="{ display: "inline-flex", gap: "0.75rem", flexWrap: "wrap", justifyContent: "center", alignItems: "center", }" > <WindBarb direction="90" magnitude="5" label="value" title="5" size="44" summary="false" /> <WindBarb direction="90" magnitude="15" label="value" title="15" size="44" summary="false" /> <WindBarb direction="90" magnitude="32" label="value" title="32" size="44" summary="false" /> <WindBarb direction="90" magnitude="55" label="value" title="55" size="44" summary="false" /> <WindBarb direction="90" magnitude="80" label="value" title="80" size="44" summary="false" /> </span> ``` ## When to use it [#when-to-use-it] * **Good for** — wind or current direction + strength, traffic flow, net migration, request routing. * **Avoid for** — exact magnitude (add `label`) or a time series (Sparkline). ## Variants [#variants] ```tsx `"> <WindBarb direction="0" magnitude="1" title="Calm" size="44" /> ``` ```tsx `"> <WindBarb direction="45" magnitude="25" mode="arrow" title="Arrow" size="44" /> ``` ```tsx `"> <WindBarb direction="225" magnitude="32" step="10" label="value" title="Wind" size="44" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <WindBarb direction="0" magnitude="0" title="Calm" size="40" /> ``` ```tsx `"> <WindBarb direction="90" magnitude="-25" title="Flipped" size="40" /> ``` ```tsx `"> <WindBarb direction="225" magnitude="5000" step="10" label="value" title="Extreme" size="40" /> ``` ```tsx `"> <WindBarb direction="225" magnitude="32" step="10" label="value" format="{ maximumFractionDigits: 0 }" locale="de-DE" title="Wind" size="44" /> ``` `format`/`locale` reach the `label="value"` numeral and the accessible summary's magnitude together — the component builds one formatter and reuses it for both. ## Why this default [#why-this-default] Quantized barbs read faster and more honestly than a scaled arrow whose length you'd have to measure against a legend — the glyph is calibrated to its `step`, so counting barbs gives the magnitude directly. A near-zero magnitude renders the conventional open circle for calm rather than a zero-length shaft, and a negative magnitude flips the bearing 180° with a dev warning. ## Accessibility [#accessibility] The accessible name is the full reading — **"Southwest (225°), magnitude 32."** Calm renders as **"Calm."** Because the glyph is self-describing, rows of barbs get their interaction from the host table or list, not from the mark. ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `direction` (required) | `number` | Degrees; 0 = up/north, clockwise. | | `magnitude` (required) | `number` | Any unit; quantized into barbs. | | `step` | `number` | Full-barb quantum (each barb = step). | | `label` | `"value" \| "none"` | Numeric magnitude beside the glyph. | | `mode` | `"barb" \| "arrow"` | "arrow" swaps quantized barbs for a plain direction arrow + label. | 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](/docs/quickstart#the-shared-grammar).

# Accessibility (/docs/accessibility) Accessibility isn't a setting in microcharts. Every chart is accessible the moment you render it, because the accessible name is generated from your data — there's no `alt` text to forget and nothing to drift out of sync when the numbers change. ## Summaries that write themselves [#summaries-that-write-themselves] By default a chart is an `img` whose accessible name is a natural-language sentence built from the series. It's the flagship feature of the library: the same words a screen reader announces are the words a crawler indexes and a model can quote. ```tsx // accessible name: // "Weekly revenue. Trending up 200%. Range 3 to 9. Last value 9."`" > ``` The name is `title` + the generated summary, joined into one sentence. The summary is deterministic — the same data always produces the same words — so it's testable, and every one of these strings in the docs is the real output, not an approximation. ### Degenerate data stays honest [#degenerate-data-stays-honest] The single most common accessibility bug in charting is a broken summary for empty, single, or flat data. microcharts produces an honest short form instead — every string below is the literal output of `describeSeries`: | Data | Accessible summary | | -------------------- | ------------------------------------------------ | | `[]` / all-null | `No data.` | | `[7]` | `Single value 7.` | | `[5, 5, 5, 5]` | `Flat at 5.` | | `[9, 7, 8, 4, 5, 2]` | `Trending down 78%. Range 2 to 9. Last value 2.` | ## Every chart is an `img` [#every-chart-is-an-img] The accessible name is composed deterministically — no module-level id counters that could desync between server and client and cause a hydration mismatch. Two levels: * **Default** — a chart renders `role="img"` with a computed `aria-label` (and an id-less ``). Nothing to wire; it just has a name. * **Explicit `id`** — pass an `id` and the chart upgrades to a `<title>`/`<desc>` pair referenced by `aria-labelledby`, the richest form, for when you want the title and description addressable. Override the whole sentence with a string when you have better words than the generator: ```tsx <Sparkline data={data} summary="Revenue per week, Q3 — up 40% and accelerating." /> ``` ## Decorative opt-out [#decorative-opt-out] When the surrounding text already describes the data — the common case for a word-sized chart *inside* a sentence — mark the chart decorative with `summary={false}` so screen readers skip the redundancy rather than reading it twice. ```tsx <p> Revenue climbed steadily <Sparkline data={data} summary={false} /> through the quarter. </p> ``` A decorative chart renders `aria-hidden="true"` instead of `role="img"` — it leaves the accessibility tree entirely, and no `<title>` or `<desc>` is emitted. On an `/interactive` entry the same call resolves the name: with nothing left to announce, the wrapper drops `role="img"` and `tabIndex={0}` and takes `aria-hidden="true"` instead — so there's nothing to tab to or activate, and the static and interactive entries tell one story. ## One interaction contract [#one-interaction-contract] The `/interactive` entries share a single contract across the catalog: learn it on a Sparkline and it already holds on an ActivityGrid, a Dumbbell, or a Waterfall. What differs between charts is only what a *unit* is — a point, a bar, a day cell, a segment, a pair — and each chart's page names its own. **Roving focus, one tab stop.** A chart is one focusable element (`role="img"`, `tabIndex={0}`), never a tab trap of one stop per data point. Arrow keys rove between units: **←/↑** move to the previous unit, **→/↓** to the next — both axes, so a grid navigates the same way a line does. **Home** and **End** jump to the first and last unit. **Active vs selected.** Hovering or roving makes a unit *active* — a transient read that clears when the pointer leaves or focus blurs. **Enter** or **Space** (or a click, or a tap) *selects* it, which **pins** the readout so it survives blur and pointer-leave — a keyboard user can move focus elsewhere and the pinned value stays on screen. Selecting the same unit again clears it, and **Escape** clears the selection from anywhere. The two states are visually distinct, so "where I am" and "what I kept" never read as the same thing. **Touch.** A tap pins a unit exactly like a click; dragging across the chart scrubs the active unit continuously. A drag is treated as a scrub, never mistaken for a tap, so scrolling past a chart can't pin a value by accident. **Announcements.** Every change of active or selected unit is written into a polite live region, so a keyboard or screen-reader user reads the same detail a mouse user gets from the hover chip. The picker fires only when the *unit* changes, not on every pointer move, so sweeping across a chart announces once per unit crossed rather than once per pixel. The callbacks mirror the states exactly. `onActive` fires as the active unit changes; `onSelect` fires on selection. Both receive a `MicroDatum` — `{ index, value, label?, formatted? }`, where `index` identifies the unit, `value` is that unit's primary encoded number (`null` when the unit encodes nothing), and `formatted` is the exact string the chart's own readout chip would show — or `null` when the chart clears. Selection is controllable with `selectedIndex`, or seeded once with `defaultSelectedIndex`. To move the value out of the chart entirely — a KPI number, a sentence, a cell that updates as you hover — set `readout={false}` to keep the crosshair but drop the in-chart chip, and render `datum.formatted` from `onActive` yourself. Charts with only **one** unit — Delta, Progress, StatusDot, Bullet, and the rest of the scalar set — have nothing to rove between, so they take `onSelect` alone (click, tap, Enter, or Space) and carry no selection state. **Values that change on their own.** Fifteen single-value charts built for updating KPI cards take `live` (default `true`): when the value changes, the new reading is re-announced through the polite region without anyone touching the chart. Set `live={false}` to silence it. A few throttle that announcement so a streaming value never floods the buffer: | Chart with `live` | Announcement throttle | | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | Progress | whole-percent steps only | | MoonPhase, FillWord | at most once per second | | Delta, ProgressRing, StatusDot, TrendArrow, Thermometer, Hourglass, FatDigits, TallyMarks, DicePips, Honeycomb, PictogramRow, BalanceBeam | none — every change announces | Two charts throttle without taking `live` at all: **EtaBar** and **TapeGauge** re-announce their reading as it changes, but never more often than `announceEvery` milliseconds — 10 s and 5 s by default, and tunable per instance. Three charts sit outside the contract, deliberately: **MinimapStrip** is a viewport-window slider (`role="slider"`, with its own `onWindowChange([lo, hi])` range payload), **TokenConfidence** flows as inline HTML text and moves real focus onto each *flagged* token span — confident tokens carry no mark and are skipped — and **WindBarb** ships static-only. Static entries carry no listeners at all; every bit of this is opt-in. ## Color is never the only channel [#color-is-never-the-only-channel] Direction and state are always doubled, so a chart survives with no color at all: * **Delta** pairs a ▲/▼ glyph with its color — the glyph carries the sign. * **SparkBar** encodes sign by *position* above or below the baseline, not hue. * **ActivityGrid** always ships a numeric summary alongside its intensity ramp. The default stroke tokens are chosen against a **4.5:1 contrast** target on the page backgrounds they're designed for, and the dark values are hand-tuned per token rather than inverted, so nothing washes out in dark mode. Contrast against *your* surface is still yours to check — charts paint no background, so a mark inherits whatever you place it on. ## Internationalization and RTL [#internationalization-and-rtl] Nothing about a chart is hard-coded to English or to left-to-right layout. * **Localized numbers.** Every rendered number and every number in the summary goes through `Intl.NumberFormat`. Pass `locale` and `format` and the digits, grouping, and units follow the reader's locale: ```tsx <Sparkline data={data} locale="de-DE" format={{ style: "currency", currency: "EUR" }} /> ``` See [Formatting & scale](/docs/formatting) for the full `format` / `locale` story, including the exported `makeFormatter` helper for matching your prose numbers to a chart's. * **Localized words.** The summary templates are a swappable contract (`SummaryStrings`; the English set ships as the exported `EN` dictionary). Spread `EN`, override the keys you're translating, and pass the result as `strings` — static and `/interactive` entries both accept it, so a server-rendered chart localizes without shipping any client JavaScript. Or override the whole sentence with a `summary` string. Either way the accessible name, the live-region announcements, and the readout chip on an interactive entry all speak your language, because all three read from the same dictionary. Six charts don't take `strings` on their static entry: Sparkline, ActivityGrid, and MusicStaff accept it on the `/interactive` entry only, while SparkBar, Delta, and Bullet compose their sentence inline — `summary` is the translation seam there. `summary` and `strings` stay the entire text surface, and that is now enforced rather than asserted. A guard renders 22 interactive entries — the readouts are where the drift lives, and they only exist in a browser — each with a `strings` object of sentinel tokens, and fails on any English left in the output. It was written because the claim had quietly stopped being true: readouts had accumulated words like "median", "vs" and "queued" in component code, which is exactly the drift a guard catches and a promise does not. The generator itself is exported too: `import { describeSeries } from "@microcharts/react"` returns the exact sentence for a series, handy for tests, tooltips, or feeding a model. * **RTL layouts.** A chart is direction-neutral SVG with a localized text name, so it drops into an RTL document without breaking — it's an `img`, not a run of text. Time-ordered charts keep their conventional oldest-to-newest reading order; you localize the summary and the number formatting, which is what a screen-reader user actually hears. ## System preferences, handled [#system-preferences-handled] * **`prefers-reduced-motion`** — entrance and update animations resolve instantly to their final state. Static charts have no `animate` prop and run no JavaScript animation; the one thing that moves inside a static host is `<Marker celebrate>`, whose particle burst is a pure-CSS one-shot that reduced motion also stills. * **`forced-colors`** — data ink maps to system `CanvasText`, accents to `Highlight`, muted marks to `GrayText`, so a Windows High Contrast user sees a correct chart, not a blank box. * **`prefers-contrast`** — strokes thicken and bands deepen automatically. ## Verify it yourself [#verify-it-yourself] Because the summary is deterministic and the markup is plain SVG, accessibility is testable in CI, not a manual audit: ```tsx import { axe } from "vitest-axe"; const { container } = render(<Sparkline data={data} title="Revenue" />); expect(await axe(container)).toHaveNoViolations(); // and assert the exact announced sentence: expect(container.querySelector("[role=img]")).toHaveAccessibleName( "Revenue. Trending up 200%. Range 3 to 9. Last value 9.", ); ``` # AI-native (/docs/ai) Most chart libraries are written for a human with a mouse. microcharts is written so a **model** can draw a chart mid-sentence and a **person** can trust it. Two properties make that work: every chart renders from plain `data`, and every chart carries a generated, human-readable summary — the same sentence a screen reader speaks, a crawler indexes, and a model can quote back. Nothing is hidden in pixels, so a few tokens of text become a real, accessible instrument. > Above is the real thing, not a video: a scripted reply streams in, and the chart syntax it emits becomes shipped microcharts the instant each fence closes. Everything below is the contract behind it. The AI reply is the newest home for a word-sized chart, not the only one — the same component lives in a product UI, a rendered report, and inline in docs like these. This page is the model-facing contract; [Where they live](/docs#where-they-live) shows the rest. ## The grammar [#the-grammar] A model emits a chart in one of two forms — both deliberately forgiving, the kind of thing a model produces reliably mid-stream. Pick a type and a form to see exactly what it writes, what it renders, and the React it's equivalent to: The grammar has two forms — a fenced `microchart` block for a standalone chart, or an inline `microchart <type> <data>` span inside a sentence. Body is whitespace/comma numbers, or key=value for composites. **Sparkline** — trend over time ```microchart sparkline 132 148 141 165 159 182 176 203 ``` Equivalent React: ```tsx <Sparkline data={[132, 148, 141, 165, 159, 182, 176, 203]} title="Revenue" /> ``` **SparkBar** — magnitude per period (signed values = win/loss) ```microchart sparkbar 6 9 5 11 7 12 8 10 ``` Equivalent React: ```tsx <SparkBar data={[6, 9, 5, 11, 7, 12, 8, 10]} title="Deploys per day" /> ``` **Delta** — one signed change or ratio ```microchart delta +0.184 ``` Equivalent React: ```tsx <Delta value={0.184} title="Week over week" /> ``` **Bullet** — a value against a target (value= target= bands=) ```microchart bullet value=72 target=80 bands=50,90 ``` Equivalent React: ```tsx <Bullet value={72} target={80} bands={[50, 90]} title="Quota attainment" /> ``` **ActivityGrid** — cadence / intensity over a period ```microchart activity 0 2 1 3 4 2 1 3 2 4 3 2 ``` Equivalent React: ```tsx <ActivityGrid data={[0, 2, 1, 3, 4, 2, 1, 3, 2, 4, 3, 2]} layout="strip" title="Commit activity" /> ``` The body is whitespace- or comma-separated numbers for series charts, or `key=value` pairs for composites. These five cover the questions an assistant answers most — *trend, magnitude, change, attainment, cadence* — but the same pattern extends to [any chart in the catalog](/docs/charts): name a type, pick a body convention, map it to that chart's import. ## Wire it up [#wire-it-up] Turning the grammar into components is a parser and a `switch` — no framework, a few lines. ### Parse the stream [#parse-the-stream] Pull fenced blocks and inline spans out of partially-streamed Markdown. A fence that hasn't closed yet stays raw, then morphs the moment it does. ```ts const FENCE = /```microchart (\w+)\n([\s\S]*?)```/g; const INLINE = /`microchart (\w+) ([^`]+)`/g; const nums = (b: string) => b.split(/[\s,]+/).map(Number).filter(Number.isFinite); const kv = (b: string) => Object.fromEntries( b.split(/\s+/).flatMap((t) => { const i = t.indexOf("="); return i > 0 ? [[t.slice(0, i), t.slice(i + 1)]] : []; }), ); ``` ### Map type → component [#map-type--component] One `switch`. Because geometry is pure and charts render from `data` alone, the model's chart is identical to one you'd write by hand. ```tsx import { Sparkline } from "@microcharts/react/sparkline"; import { SparkBar } from "@microcharts/react/sparkbar"; import { Delta } from "@microcharts/react/delta"; import { Bullet } from "@microcharts/react/bullet"; import { ActivityGrid } from "@microcharts/react/activity-grid"; export function ChartBlock({ type, body }: { type: string; body: string }) { switch (type) { case "sparkline": return <Sparkline data={nums(body)} title="Series" />; case "sparkbar": return <SparkBar data={nums(body)} title="Per period" />; case "delta": return <Delta value={Number(body.trim())} title="Change" />; case "bullet": { const p = kv(body); return ( <Bullet value={+p.value} target={p.target ? +p.target : undefined} bands={p.bands?.split(",").map(Number)} title="Attainment" /> ); } case "activity": return <ActivityGrid data={nums(body)} layout="strip" title="Cadence" />; default: return null; // unknown type → leave the text as-is } } ``` ### Render inline vs block [#render-inline-vs-block] An inline chart is decorative — the sentence describes it, so pass `summary={false}`. A standalone chart keeps its summary; give it a `title`. Wrap every inline SVG mark in `className="mc-inline"` — the class ships in `@microcharts/react/styles.css` (imported once in the Quickstart). It seats the mark on the text baseline, so it rides the line like a word in any font. Leave `Delta` bare; it is a text metric and owns its own baseline already. ```tsx NVDA closed +3.8%{" "} <span className="mc-inline"> <TrendArrow value={0.038} summary={false} /> </span>{" "} on the session — up <Delta value={0.038} summary={false} /> week over week. ``` ## Prompt the model [#prompt-the-model] A few lines teach the grammar. Reach for the technique that matches how the model is driven — structured output and tool calls first, since that's how most agents run today: #### Structured JSON The default for anything production. Have the model return JSON and map it yourself — no parsing of prose. Constrain `type` to an enum and the output is always renderable. ```tsx type ChartSpec = | { type: "sparkline" | "sparkbar" | "activity"; data: number[]; title?: string } | { type: "delta"; value: number; title?: string } | { type: "bullet"; value: number; target?: number; bands?: number[]; title?: string }; // model returns ChartSpec (JSON mode / response_format) → render directly function Chart(spec: ChartSpec) { switch (spec.type) { case "sparkline": return <Sparkline data={spec.data} title={spec.title} />; case "bullet": return <Bullet {...spec} />; // …one arm per type } } ``` #### Tool use Expose a single tool the model calls when a chart helps. Its arguments *are* the chart spec, so there's nothing to parse and the schema enforces the shape. ```ts const renderChart = { name: "render_chart", description: "Render a microchart when a number series helps the reader.", input_schema: { type: "object", required: ["type"], properties: { type: { enum: ["sparkline", "sparkbar", "delta", "bullet", "activity"] }, data: { type: "array", items: { type: "number" } }, value: { type: "number" }, target: { type: "number" }, bands: { type: "array", items: { type: "number" } }, title: { type: "string" }, }, }, }; // on tool_use → <Chart {...toolCall.input} /> ``` #### System prompt For free-form chat, drop this into the system message — enough for a capable model to emit valid blocks unprompted. ```text When a number series would help, emit a chart block instead of prose. Fenced for a standalone chart, inline `microchart …` for a word-sized one: ```microchart sparkline 132 148 141 165 159 182 176 203 ``` Types: sparkline · sparkbar (signed = win/loss) · delta (one signed ratio) · bullet (value= target= bands=) · activity (intensities). Never invent a pie or gauge — they aren't supported. ``` #### Few-shot When you want a specific house style, show one exchange. Models mirror the shape of the example. ```text User: How did deploys trend this week? Assistant: Steady, with a strong Thursday: ```microchart sparkbar 6 9 5 11 7 12 8 10 ``` User: And are we on track for the quota? Assistant: Close — `microchart delta +0.184` week over week puts us here: ```microchart bullet value=72 target=80 bands=50,90 ``` ``` #### Guardrails Never trust generated data blindly. Validate the type, coerce the numbers, and fall back to text when a block is malformed — the summary makes a graceful fallback trivial. ```ts const KNOWN = new Set(["sparkline", "sparkbar", "delta", "bullet", "activity"]); function safeBlock(type: string, body: string) { if (!KNOWN.has(type)) return null; // unknown type → render raw text const data = nums(body); if (type !== "delta" && data.length === 0) return null; // no numbers → skip return { type, body }; // charts handle empty/NaN/±∞ already } ``` ## Where it runs [#where-it-runs] A chart is plain text and JSON, so anything that reads or writes text can emit one and render it back — no SDK, no partnership, no island bridge. That spans the whole stack a model runs in today: the **chat assistants** that answer in prose, the **coding agents and IDEs** that scaffold the components from the typed catalog, and the **frameworks and SDKs** that wire tool-call output straight to charts. None of these is an integration we built — they work because the output is just text. - **Chat assistants & models** (emit a chart block mid-reply): Claude, ChatGPT, Gemini, Grok, DeepSeek, Kimi, Meta AI, Mistral, Perplexity, Qwen, Poe - **Coding agents & IDEs** (scaffold components from the typed catalog): Cursor, Claude Code, Codex, v0, opencode, Antigravity, Windsurf, Zed, Cline, Replit, Continue, Warp, Amp, Roo Code, StackBlitz, JetBrains AI, Pi, Copilot - **Frameworks & SDKs** (map tool-call output to charts): Vercel AI SDK, OpenAI Agents, LangChain, Anthropic SDK, Hugging Face, Ollama, Pydantic AI, CrewAI ## Integration scenarios [#integration-scenarios] Every path from model output to a rendered chart, with the one thing each needs. #### Streaming chat reply — morph blocks as they close Parse the partial Markdown on every token; render a fence as raw text until it closes, then swap in the chart. Word-sized charts land inside the sentence, standalone ones below it. The live demo at the top of this page is exactly this shape. ```tsx // on each streamed chunk: const nodes = parse(accumulatedText); // text | { type, body, closed } return nodes.map((n) => n.type === "text" ? <Inline text={n.v} /> : n.closed ? <ChartBlock type={n.type} body={n.body} /> : <pre>{n.raw}</pre>, // still streaming → show raw ); ``` #### React Server Components — zero client JavaScript Static entries are hook-free, so an RSC assistant renders the model's charts to HTML on the server. Nothing hydrates; the chart ships as markup. Add `/interactive` only where the reader needs to interrogate a value — hover, keyboard, touch, or click-to-pin — and read it back with `onActive` / `onSelect`. Every chart but WindBarb has an interactive twin; `catalog.json` names it per entry, so an agent never has to guess. ```tsx import { Sparkline } from "@microcharts/react/sparkline"; // no "use client" export default async function Answer({ spec }: { spec: ChartSpec }) { return <ChartBlock type={spec.type} body={spec.body} />; // pure SVG, server-rendered } ``` #### Tool / function-call output — rows straight to charts When a tool returns rows, render them instead of asking the model to describe them in prose — a `Sparkline` per row, a `Bullet` for a KPI against target. ```tsx {rows.map((r) => ( <tr key={r.id}> <td>{r.name}</td> <td><Sparkline data={r.history} summary={false} /></td> <td><Bullet value={r.value} target={r.goal} summary={false} /></td> </tr> ))} ``` #### Programmatic & React-free — outside a component tree Need a chart in a README, an email, or a non-React runtime? Render the static component to an SVG string on the server. Static entries are hook-free and listener-free, so the markup they emit stands on its own. ```ts import { renderToStaticMarkup } from "react-dom/server"; import { Sparkline } from "@microcharts/react/sparkline"; const svg = renderToStaticMarkup(<Sparkline data={data} title="Revenue" />); // → a self-contained <svg> string for anywhere HTML goes ``` #### Validation & safety — malformed data never breaks a render Every chart already handles the degenerate cases — empty, single value, all-equal, nulls, NaN, ±Infinity — with an honest short summary instead of a broken chart. Layer the type/coercion guardrails above and a bad block downgrades to plain text, never a crash. ## Machine-readable surfaces [#machine-readable-surfaces] Real, generated routes — the substance behind "AI-native", not a slogan. Point an agent here and it reads the true API instead of guessing. - [/llms.txt](/llms.txt): A hand-curated index of the docs for LLM tools, with explicit “does not support” notes to head off hallucinations. - [/llms-full.txt](/llms-full.txt): Every doc page concatenated into one text file — drop the whole API into a context window at once. - [/catalog.json](/catalog.json): Machine catalog: each chart’s name, import paths, data shape, and props (plus a shared-grammar block) — generated from the same registry that builds this site, and validated in CI against its JSON Schema. - [*.md mirrors](/docs/ai.md): Append .md to any docs page for a Markdown copy an agent reads without parsing HTML — every component expanded to text and code. The `.md` mirrors are real static files — `/docs/ai` has a sibling `/docs/ai.md` — so they resolve on any host, with no runtime, rewrite, or middleware. This site also deploys behind a small Cloudflare Worker that runs on `/docs/*` only: send `Accept: text/markdown` and the same doc URL returns the mirror inline, with `Vary: Accept` on both the Markdown and the HTML response. That negotiation is a convenience layered on top of the mirrors, never a dependency — appending `.md` always works. `/llms.txt` points at one more surface the cards don't: [`/agent-setup.md`](/agent-setup.md), the paste-and-run setup prompt for a coding agent, extracted from the [Quickstart](/docs/quickstart) so the two can't drift. Or skip the URL entirely: <CopyAgentSetup /> ## The whole contract, on one card [#the-whole-contract-on-one-card] Don't make a model memorize the catalog — [All charts](/docs/charts) files every type by the question it answers, and the [Charts index](/charts) shows them at a glance. Everything an agent needs to emit correct microcharts fits on one card — copy it straight into a system prompt: **Agent cheat sheet.** Grammar: - `microchart sparkline` — 132 148 141 165 159 182 176 203 (trend over time) - `microchart sparkbar` — 6 9 5 11 7 12 8 10 (magnitude per period (signed values = win/loss)) - `microchart delta` — +0.184 (one signed change or ratio) - `microchart bullet` — value=72 target=80 bands=50,90 (a value against a target (value= target= bands=)) - `microchart activity` — 0 2 1 3 4 2 1 3 2 4 3 2 (cadence / intensity over a period) Rules: - Import each chart from its own subpath — `@microcharts/react/<name>`; add `/interactive` only for hover and keyboard. - Static charts are hook-free — valid inside a React Server Component, zero client JavaScript. - Pass `data` and a `title`; the generated summary handles accessibility. Use `summary={false}` only when a chart is decorative inside describing text. - Never add a runtime dependency, and never reach for a pie or gauge — they aren't shipped. Surfaces: /llms.txt · /llms-full.txt · /catalog.json · *.md mirrors That's the entire surface area: a grammar a model already knows how to write, and charts a person can trust on sight. Point an assistant at [`/llms.txt`](/llms.txt) — or the fuller [`/llms-full.txt`](/llms-full.txt) and the machine-readable [`/catalog.json`](/catalog.json) — or start from the [Quickstart](/docs/quickstart) and render your first chart in minutes. # Annotations (/docs/annotations) Annotations answer "what should the reader compare this against?". 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 whispers: the 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 — so the data never competes with its context. ```tsx <TargetZone y={[40, 60]} /> <Threshold y={65} label="SLA" /> <Marker x={3} label="deploy" /> </Sparkline>`" > <Sparkline data="[48, 52, 45, 58, 51, 47, 55, 49, 71, 64, 57, 52]" title="p95 latency" width="200" height="48"> <TargetZone y="[40, 60]" /> <Threshold y="65" label="SLA" /> <Marker x="3" label="deploy" /> </Sparkline> ``` ## Install [#install] The annotation layer is its own \~1.5 kB entry. A host that renders no annotations pays only a tiny children walker; the mark renderers ship with this import. ```tsx import { Threshold, TargetZone, Marker, Callout } from "@microcharts/react/annotations"; ``` ## The vocabulary [#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 rest as a quiet starburst. * **`<Callout x={5} y={45} label="dip" />`** — one narrated 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. ```tsx <Marker x={9} celebrate label="10k!" /> </Sparkline>`" > <Sparkline data="[3, 4, 5, 5, 6, 8, 9, 11, 12, 14, 15, 17]" title="Signups" width="160" height="36"> <Marker x="9" label="10k!" /> </Sparkline> ``` ```tsx <Callout x={3} y={58} label="cache miss" /> </Sparkline>`" > <Sparkline data="[48, 52, 45, 58, 51, 47, 55, 49, 51, 46]" title="Latency" width="160" height="40"> <Callout x="3" y="58" label="cache miss" /> </Sparkline> ``` ## The same child, any host [#the-same-child-any-host] The children don't know which chart drew them — 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. ```tsx <TargetZone y={[3, 8]} /> <Threshold y={10} label="cap" /> </SparkBar>`" > <SparkBar data="[4, 7, 3, 9, 6, 8, 5, 11, 7, 9]" title="Deploys per day" width="160" height="44"> <TargetZone y="[3, 8]" /> <Threshold y="10" label="cap" /> </SparkBar> ``` ## Every value-series host [#every-value-series-host] Every **value-series** chart hosts annotations — the charts with a continuous value axis and an index / slot / time x-axis, so 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-y don't host them, by design — there's no shared `y` for a `<Threshold>` to land on: | Why it can't host | Examples | | ----------------------------- | ---------------------------------------- | | Scalar readout — no axis | Delta, FatDigits, StatusDot, Thermometer | | Part-to-whole — y is a share | MicroDonut, SegmentedBar, Funnel | | Value encoded as colour | HeatStrip, ActivityGrid, the calendars | | Value against value | QuadrantDot, MicroScatter, BiasStrip | | Pure timeline — no value axis | the event/phase timelines | Most still accept children as a plain pass-through, so an annotation placed inside one renders nothing and warns in dev; a few — Delta among them — take no children at all, and it's a type error. <AnnotationHostShowcase /> ## Honesty rules [#honesty-rules] * A coordinate outside the host's domain **clamps to the edge at 0.4 opacity** — visibly off-scale, never silently dropped. * Annotations never touch the auto summary: the data description stays pure. To narrate 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 it's kept inside the chart by one of two mechanisms. `Threshold`, `TargetZone` and `Callout` **truncate**: a label longer than its available run is cut and given a trailing `…`. `Marker` instead **flips its anchor** — a label near the right edge draws leftward from the mark rather than off the chart — so a moment mark never loses characters. * Reference hairlines draw at a fixed 1-unit weight, deliberately exempt from `--mc-density`, so tightening the density never thickens the context ink along with the data. The one exception is the `Callout` elbow, drawn a shade lighter at 0.75, because it's a leader line pointing at data rather than a reference the reader measures against. # Composition (/docs/composition) microcharts are built to sit *inside* an interface, not in a chart pane of their own. This page documents the placement decisions the gallery demos make — the surface they need, the size and props each context wants, and how to compare several at once — so nothing is left implied. If a demo on this site looks right, this is why. ## Charts sit on your surface [#charts-sit-on-your-surface] Every chart is transparent: it **never paints its own background**. That's deliberate — a chart drops onto whatever surface it lands on and picks up the ink color from `--mc-stroke` (which tracks light/dark for you). The one decision that's yours: give it a container with real contrast. * Put the chart on a surface with enough contrast for a 1.5 px line — the data, valence, and accent inks all clear 4.5:1 on the built-in light and dark themes. (`--mc-neutral`, the muted context ink for baselines and ghost marks, sits at 3.5:1 — comfortably past the 3:1 bar for non-text, and deliberately quieter than the data.) * Don't wrap it in a low-contrast tint and expect the chart to compensate; it won't, by design. * Need the ink to differ from the page (charts on a colored panel, frosted glass)? Set `--mc-stroke` (and valence tokens if needed) on the container — see [Theming](/docs/theming#frosted-or-translucent-surfaces). Don't override `.mc-root` paint rules. > The gallery renders each demo inside a panel with a normal card background and a hairline border. Nothing about that panel is part of the library — it's just a surface. Your app's cards, table rows, and headers are surfaces too. ## In a sentence [#in-a-sentence] A word-sized chart in running prose scales with the **font** and aligns to the text baseline; drop its endpoint dots and it reads as one glyph, not a widget. (There are no axes to drop — no chart in the catalog draws one.) Wrap it in `mc-inline` (shipped in `styles.css`), pass `dots="none"`, and mark it decorative with `summary={false}` so a screen reader hears the sentence, not a second description. ```tsx p95 latency this week{" "} <span className="mc-inline"> <Sparkline data={latency} dots="none" summary={false} width={64} height={16} /> </span>{" "} — trending down. </p>`" > {/* Text as JSX expressions ({"…"}), never bare prose: MDX blockifies multiline bare text inside a JSX <p> into nested <p>s (hydration error). Expressions also survive prettier's md/mdx prose-wrap, which re-expands a single line. */} <p className="max-w-md text-[0.95rem] leading-relaxed"> {"p95 latency this week "} <span className="mc-inline"> <Sparkline data="[48, 45, 44, 40, 38, 36, 33, 31]" dots="none" summary="false" width="64" height="16" /> </span> {" — trending down."} </p> ``` See [Sizing](/docs/sizing#inline-in-a-sentence) for the `em`-based variant that scales with the surrounding type size. ## In a table cell [#in-a-table-cell] In a dense table, each row already carries a name and a number — the chart's job is the *shape* between them. So it goes small, with dots off, decorative (`summary={false}`), and the numeric column stays `tabular-nums` so figures line up. ```tsx <td>checkout-api</td> <td><Sparkline data={latency} dots="none" summary={false} width={64} height={18} /></td> <td className="tabular-nums">31 ms</td> </tr>`" > <table className="w-full max-w-sm text-sm tabular-nums"> <tbody className="[&>tr+tr]:border-t [&>tr+tr]:border-fd-border/60"> {[ { name: "checkout-api", data: [48, 45, 44, 40, 38, 36, 33, 31], now: "31 ms" }, { name: "auth-api", data: [12, 13, 12, 14, 13, 15, 14, 16], now: "16 ms" }, { name: "search-api", data: [80, 78, 82, 79, 81, 80, 79, 78], now: "78 ms" }, ].map((s) => ( <tr key={s.name}> <td className="py-1.5 pr-3 text-fd-muted-foreground">{s.name}</td> <td className="py-1.5"> <Sparkline data={s.data} dots="none" summary={false} width={64} height={18} /> </td> <td className="py-1.5 pl-3 text-right text-fd-muted-foreground">{s.now}</td> </tr> ))} </tbody> </table> ``` ## In a KPI card [#in-a-kpi-card] Here the big number leads and the chart is context beneath it. Give it a little more height, turn `fill` on so it reads as a filled area at a glance, and keep it decorative — the figure and label already say what it is. ```tsx <span className="figure">1,600</span> <span className="unit">concurrent, now</span> <Sparkline data={connections} fill summary={false} width={120} height={32} /> </div>`" > <div> <div className="text-fd-muted-foreground text-xs"> Active connections </div> <div className="mb-1 flex items-end gap-2"> <span className="text-3xl tabular-nums"> 1,600 </span> <span className="mb-1 text-fd-muted-foreground text-xs"> concurrent, now </span> </div> <Sparkline data="[1240, 1310, 1290, 1420, 1380, 1510, 1470, 1600]" summary="false" width="120" height="32" /> </div> ``` ## In a tab or button [#in-a-tab-or-button] A spark beside a label previews what's behind the tab. It goes *tiny* — the label is the primary read, the chart a hint — so drop to a small box with no dots. ```tsx CPU <Sparkline data={cpu} dots="none" summary={false} width={40} height={14} /> </button>`" > <div className="flex flex-wrap gap-1.5"> {[ { name: "CPU", data: [62, 65, 61, 68, 70, 66, 72, 75], on: true }, { name: "Memory", data: [48, 47, 49, 46, 45, 44, 43, 42], on: false }, { name: "Network", data: [120, 118, 122, 119, 121, 120, 119, 118], on: false }, ].map((m) => ( <span key={m.name} className={`inline-flex items-center gap-2 rounded-md border px-2.5 py-1.5 text-sm ${ m.on ? "border-fd-primary/40 bg-fd-primary/5 text-fd-foreground" : "border-fd-border text-fd-muted-foreground" }`} > {m.name} <Sparkline data={m.data} dots="none" summary={false} width={40} height={14} /> </span> ))} </div> ``` ## Small multiples: one shared scale [#small-multiples-one-shared-scale] The most important composition decision, and the easiest to get silently wrong: when you place several sparklines in a row to *compare* them, they must share one vertical scale. Auto-scaling each to its own range makes a flat line and a spiking one look identical — a real correctness bug. `SparkGroup` fixes it structurally. It reads every child's `data`, computes **one** domain across all of them, and enforces **one** physical size — so a row of charts is honestly comparable. It's hook-free and RSC-safe, and any child's own explicit `domain`/`width` still wins. ```tsx <Sparkline data={us} summary={false} /> <Sparkline data={eu} summary={false} /> <Sparkline data={apac} summary={false} /> </SparkGroup>`" > <SparkGroup width="80" height="22"> <Sparkline data="[20, 22, 21, 24, 23, 25, 24, 26]" summary="false" /> <Sparkline data="[60, 58, 62, 59, 61, 60, 59, 58]" summary="false" /> <Sparkline data="[5, 8, 6, 12, 10, 15, 14, 18]" summary="false" /> </SparkGroup> ``` Pass `zero` when the group is bars or areas (so the shared domain anchors at zero), or an explicit `domain={[min, max]}` when you want a fixed frame instead of the data's own range (`domain` defaults to `"shared"`). Two details worth knowing. Only children that actually carry a `data` prop get the scale and size injected — plain wrappers, labels, and captions pass through untouched, so you can interleave them without them collecting stray DOM attributes. And the group renders one `<div className="mc-group">`, an `inline-flex` row that wraps: its gap is `--mc-gap` scaled by `--mc-density`, and `className`/`style` on `SparkGroup` land on that div if you want a different layout. ## Decorative vs. summarized — the `summary` decision [#decorative-vs-summarized--the-summary-decision] You'll notice `summary={false}` on nearly every demo above. That's a deliberate call, not a habit: * **Standalone chart** (the one thing in its region): keep the auto-summary on. It's the accessible name a screen reader announces — real, generated from the data. * **Repeated or captioned chart** (table rows, tabs, a chart next to a number that already states it): pass `summary={false}`. The surrounding text is the accessible name; a per-chart summary would just make a screen reader read the same thing many times. This is the only accessibility lever you routinely touch. Everything else — the `role="img"`, the `<title>`, and the whole interaction contract on interactive entries (roving arrow keys, select-to-pin with **Enter** or **Space**, touch scrub, live announcements) — is automatic. See [Accessibility](/docs/accessibility). # Design notes (/docs/design-notes) microcharts has opinions, and they're baked into the defaults so you rarely have to think about them. Here's the reasoning behind the ones that shaped the library, in case you're curious. ## Direct labels beat chrome [#direct-labels-beat-chrome] At this size, an axis, a legend, and a gridline all cost more ink than they return — so there are none. A value sits at the end of the line; a min and max mark themselves. The chart is almost all data, which is exactly what you want a reader to spend their attention on. ## Areas anchor at zero [#areas-anchor-at-zero] A filled Sparkline always measures from zero, because an area floating on an arbitrary baseline exaggerates change. Length should mean magnitude, honestly — the chart never says more than the numbers do. ## Color encodes, never decorates [#color-encodes-never-decorates] There's one accent per context, and a color change always means a change in meaning. Positive and negative come from a color-blind-safe pair, and they're always doubled by a glyph or a position, so the chart survives with no color at all. A preset can restyle a chart without ever changing what it says. ## Static first, interactivity opt-in [#static-first-interactivity-opt-in] Nearly every chart ships as two entries (WindBarb is static-only). The default is pure SVG — hook-free, listener-free, safe inside a React Server Component, and it renders to HTML with zero client JavaScript. Hover, roving keyboard focus, touch scrub, select-to-pin, and live announcements live in a separate `/interactive` subpath you import only where you need them. The line between the two is never blurred, so you never pay for interactivity you didn't ask for, and a static chart can never accidentally drag a listener into your server bundle. The interactive entry composes the static one rather than re-implementing it, so the interactive rendering can't drift from the static one. Every multi-unit chart resolves a gesture to a navigable *unit* through the same kernel — so interaction is one thing to learn across the catalog, not one dialect per chart. Single-unit charts have nothing to rove between and take `onSelect` alone. ## One grammar, not an options bag [#one-grammar-not-an-options-bag] `data` alone always renders something correct. A prop name means the same thing on every chart — `title`, `color`, `domain`, `format`, `summary` — so what you learn on one chart transfers to all of them. Variants are props; a genuinely different data shape is a different component rather than a deeper options object. Annotations — a threshold, a target zone, a marker — are children you nest, not configuration you pass. The result is an API you can mostly guess. ## Summaries are a feature, not an afterthought [#summaries-are-a-feature-not-an-afterthought] The natural-language sentence each chart generates from its data is the product, not a compliance checkbox. It's the accessible name a screen reader speaks, the text a crawler indexes, and the string a model can quote — one deterministic sentence doing all three jobs. It degrades honestly on empty, single, and flat data instead of describing a chart that isn't there. See [Accessibility](/docs/accessibility) for the details. ## Small is a material, not a limit [#small-is-a-material-not-a-limit] Composition, contrast, and the auto-summary all have to survive the smallest supported size. That constraint is what makes the charts calm: there's no room for anything that isn't carrying information, so nothing decorative gets in. ## Motion lives in the interactive build, not on every chart [#motion-lives-in-the-interactive-build-not-on-every-chart] Static charts have no `animate` prop and run no animation JavaScript — the one thing that moves inside a static host is `<Marker celebrate>`, a pure-CSS one-shot burst that reduced motion stills. Only the `/interactive` entries can play an entrance, and only when you opt in with `animate` (off by default). It runs through the Web Animations API, gated on `prefers-reduced-motion`. Every entrance follows the logic of the data it draws: a line draws left-to-right along its time axis, bars grow from the baseline, a donut fills clockwise from twelve o'clock, and labels arrive last — they annotate marks that already exist. Marks decelerate into place; they never bounce, loop, or draw the eye away from the data. Motion is a property of the interactive build, not a knob bolted onto the static one, so it can't leak into a server render or turn into decoration. ## Budgets are build gates [#budgets-are-build-gates] Size isn't an aspiration here — it's a CI gate. A chart that grows past its gzip budget fails the build, the same way a failing test does, and the SSR benchmark exits non-zero when a chart drops below its render floor. The numbers on the [Performance](/docs/performance) page are never hand-typed: the sizes are re-measured from the built `dist/` on every CI run, and the throughput figures are derived from the checked-in benchmark result, so a claim can't drift from what was measured. ## One package [#one-package] All the chart types ship from a single package, `@microcharts/react`, each behind its own subpath so you only bundle what you import. The catalog's collections — core, decision, expressive, frontier — are just metadata for browsing; they're never package or import boundaries. There's no plugin to install, no engine to configure. The root barrel (`@microcharts/react`, no subpath) carries only the shared pieces, so importing it pulls in no chart code: the `Chart` root wrapper every chart composes — a `role="img"` `<svg>` with the viewBox, `title`, and generated `summary` already wired, there if you ever need to build a custom mark — plus [`SparkGroup`](/docs/composition#small-multiples-one-shared-scale) for shared-scale small multiples, [`MicroProvider`](/docs/theming#a-component-api-if-you-prefer) for theming, and the `describeSeries` / `makeFormatter` / `EN` helpers documented under [Formatting](/docs/formatting) and [Accessibility](/docs/accessibility). ## The bar for a new chart type [#the-bar-for-a-new-chart-type] A new chart earns its place only if it clears a real bar: it reads at word size (roughly 200×60 px), it tells a data story the catalog can't already tell well, it has one honest primary encoding channel, and a first-time reader can read it back without training. "It looks cool" isn't a reason. This is why the catalog prefers uncommon *questions* over uncommon *shapes*. ## What we don't ship [#what-we-dont-ship] No pie, no needle gauge, no battery, no waffle, no violin, no 3-D, no gradients-as-decoration, no drop shadows on data, no looping animation. These aren't theme options you can switch on — they're designed out, because at a glance they mislead more than they inform. Where a rejected chart answered a real question, the catalog ships a faster replacement: [Bullet](/docs/charts/bullet) or [TapeGauge](/docs/charts/tape-gauge) instead of a speedometer, [SegmentedBar](/docs/charts/segmented-bar) for comparative part-to-whole, [MicroDonut](/docs/charts/micro-donut) as a capped icon-size mix when a glyph is specifically wanted, [MicroBox](/docs/charts/micro-box) instead of a violin. # Formatting & scale (/docs/formatting) Two orthogonal decisions live here: **how numbers are written** (`format` + `locale`) and **what range they're drawn against** (`domain`). Both are part of the one grammar — the same prop name means the same thing on every chart — and both are documented per chart, but this page is the whole story in one place, since it's easy to assume a default you didn't actually get. ## One formatter, three places [#one-formatter-three-places] A chart shows numbers in three spots: the **direct labels** it draws, the **accessible summary** a screen reader announces, and — on an interactive entry — the **readout** that follows the pointer. `format` feeds *all three* from a single definition — so a currency chart's spoken summary says "$1,240", not "1240". You never format the same number twice. `format` takes either **`Intl.NumberFormatOptions`** or a **plain function** `(n) => string`. Formatters are cached (`Intl.NumberFormat` construction is expensive), keyed by locale plus options, so hundreds of instances sharing one format shape build one formatter between them — never build your own `new Intl.NumberFormat` in a component. The cache is deliberately small: it holds 64 formatters and empties completely when it fills, on the reasoning that one app uses a handful of locale × option shapes, and a bounded cache that occasionally rebuilds beats one that grows forever. Need the same formatting *outside* a chart (a matching KPI label, a table cell)? Import the exported `makeFormatter` helper so your prose numbers line up with the chart's exactly, from the same cache: ```tsx import { makeFormatter } from "@microcharts/react"; const fmt = makeFormatter({ style: "currency", currency: "USD" }, "en-US"); fmt(42); // "$42.00" ``` The arguments are positional — `makeFormatter(format, locale, defaults?)`. The third argument is the fallback used when `format` is omitted; it's how a chart supplies its own default (see `Delta` below). ```tsx `"> <Sparkline data="[1240, 1310, 1290, 1420, 1380, 1510, 1470, 1600]" width="170" height="44" label="last" format="{ style: "currency", currency: "USD", maximumFractionDigits: 0 }" title="Revenue" /> ``` ## Percent, compact, decimals [#percent-compact-decimals] Anything `Intl.NumberFormat` supports works — percent, compact notation, fixed decimals, sign display. `Delta` even defaults to a locale-aware percent, so a raw ratio reads as a change with no config: ```tsx // → +12.8% <Delta value={4200} format={{ notation: "compact" }} /> // → +4.2K <Delta value={4200} format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }} />`" > <div className="flex flex-wrap items-center gap-6 text-lg"> <Delta value="0.128" summary="false" /> <Delta value="4200" format="{ notation: "compact" }" summary="false" /> <Delta value="4200" format="{ style: "currency", currency: "USD", maximumFractionDigits: 0 }" summary="false" /> </div> ``` ## A custom function [#a-custom-function] When `Intl` can't express the unit — milliseconds, "×" multipliers, a domain-specific symbol — pass a function. It receives the number and returns the exact string to render. The value is snapped to 12 significant digits before it reaches your function, so a number a chart derived internally (`value - target`) arrives as `-3.6`, not `-3.5999999999999943` — you write for clean data, not for IEEE arithmetic. ```tsx \`\${Math.round(n)} ms\`} />`"> <Sparkline data="[48, 45, 44, 40, 38, 36, 33, 31]" width="170" height="44" label="last" format="(n) => `${Math.round(n)} ms`" title="p95 latency" /> ``` ## The interactive readout [#the-interactive-readout] Import a chart from its `/interactive` subpath and it gains a readout: a small chip that follows the pointer, or the focused datum when you rove with the keyboard. It uses the same `format` and `locale` as everything else, so a currency chart's hover value matches its label and its summary exactly. **It is deliberately terse.** The chip names the datum and its value — a Funnel stage reads `Checkout 62% (1,240)`, a Slope line reads `Brazil: 44 → 28` — and nothing else. It does not repeat the axis names, the row label already printed beside it, or the grid position the cell already occupies. These are word-sized charts; a chip wider than the chart it annotates is worse than no chip. The fuller sentence still exists. Everything the chip leaves out — the comparison, the quadrant name, the running total, the per-cycle breakdown — is announced in the chart's live region, which is what a screen reader reads. So nothing is lost by the chip being short; it is a different audience, not less information. ```tsx import { Sparkline } from "@microcharts/react/sparkline/interactive"; // the readout, the endpoint label, and the spoken summary all read "$1,600" <Sparkline data={revenue} label="last" format={{ style: "currency", currency: "USD" }} />; ``` The chip is capped at `max(100%, 14em)` wide and ellipsizes past that, so a long formatted value cannot paint across the page. If you see an ellipsis, the value is too long for the chart — shorten it with `format` (`notation: "compact"` is usually the answer) rather than widening the chart. Its prose comes from `strings`, like every other word the library renders, so a localized bundle localizes the readout too. Its colors come from `--mc-surface`, `--mc-surface-ink` and `--mc-surface-edge`; see [Theming](/docs/theming#the-readout-surface). **Put the value somewhere else.** That same terse string is handed to you: every `onActive` / `onSelect` callback receives it as `datum.formatted`, formatted with the chart's own `format` and `locale`. So you can suppress the chip and render the value in your own layout — the pattern behind a KPI card whose big number tracks a sparkline you hover: ```tsx const [reading, setReading] = useState("$1,600"); // readout={false} keeps the crosshair, drops the chip; the value lands in your <output> <output>{reading}</output>; <Sparkline data={revenue} format={{ style: "currency", currency: "USD" }} readout={false} onActive={(d) => d && setReading(d.formatted!)} />; ``` `readout={false}` hides only the chip — hover, keyboard roving, touch scrub, the live-region announcements, and both callbacks all keep working. Leave `readout` at its default (`true`) and you get the chip and the callback both. ## Locale: separators, not language [#locale-separators-not-language] `locale` is a BCP-47 tag (`"de-DE"`, `"ja-JP"`, or an array of fallbacks). It controls how numbers and dates are *written* — the thousands separator, decimal mark, currency placement — matching the reader's conventions. ```tsx // 1,600 <Sparkline data={revenue} label="last" locale="de-DE" /> // 1.600`" > <div className="flex flex-wrap items-center gap-8"> <Sparkline data="[1240, 1310, 1290, 1420, 1380, 1510, 1470, 1600]" width="150" height="40" label="last" locale="en-US" title="US" /> <Sparkline data="[1240, 1310, 1290, 1420, 1380, 1510, 1470, 1600]" width="150" height="40" label="last" locale="de-DE" title="DE" /> </div> ``` > `locale` sets number/date **formatting**. It does not translate the summary *sentence* ("Trending up 200%…") — that's the `strings` contract on [Accessibility](/docs/accessibility#internationalization-and-rtl). Pick both for a fully localized chart: `locale` for the figures, translated `strings` for the prose. ### Server rendering: pass a `locale` explicitly [#server-rendering-pass-a-locale-explicitly] Omitting `locale` means `Intl` resolves the *runtime's* default — and on a server-rendered page that runtime is the server. Node typically resolves to the host's locale while the visitor's browser resolves to theirs, so the same chart can render `1,600` into the HTML and `1.600` after hydration. React reports that as a hydration mismatch, and the mismatched text is not patched up. This is not specific to microcharts — it is how `Intl` defaults work — but charts hit it more often than most UI, because the number reaches three places at once: the label, the accessible summary, and the readout. The fix is to make the choice explicit rather than ambient: ```tsx // Deterministic: the server and the browser format identically. <Sparkline data={revenue} label="last" locale="en-US" /> ``` Pass the locale your page has already resolved (from the request, a cookie, or your i18n provider) and use the same one on both sides. If a chart is client-only, the ambient default is fine. ## Scale: the `domain` decision [#scale-the-domain-decision] `domain` sets the value range the geometry is drawn against — the vertical frame. Omit it and the chart **auto-fits to its own data**. Pass `[min, max]` to pin a fixed frame instead — so a 40–60% reading looks like 40–60% of a 0–100 scale, not a full-height line. ```tsx // auto-fit — fills the height <Sparkline data={cpu} domain={[0, 100]} /> // fixed 0–100% frame`" > <div className="flex flex-wrap items-center gap-8"> <Sparkline data="[48, 52, 49, 55, 53, 58, 54, 60]" width="150" height="44" dots="minmax" title="Auto-fit" /> <Sparkline data="[48, 52, 49, 55, 53, 58, 54, 60]" width="150" height="44" domain="[0, 100]" dots="minmax" title="Fixed 0–100" summary="false" /> </div> ``` Auto-fit is not the same everywhere. Charts whose marks read as magnitude from a baseline — `Sparkbar`, `MiniBar`, `PairedBars`, and `Sparkline` once you turn on `fill` — anchor the auto-fitted domain at **zero**, because a bar cut off above zero lies about its own length. Line charts without a fill auto-fit to the data alone. Either way, a completely flat series is padded so it still has a band to sit in rather than collapsing to a degenerate scale. This is an **honesty decision**, not cosmetics: auto-fit maximizes detail for a single series, but a fixed domain is what makes two charts comparable. To share one scale across several charts at once, use `SparkGroup` — it reads every child's `data`, computes one union domain, and injects it into any child that didn't set its own (`zero` anchors that shared domain at zero). See [Composition](/docs/composition#small-multiples-one-shared-scale). ## Dates and times [#dates-and-times] On calendar and time charts, `format` still means what it means everywhere else: it formats the **numbers**. On `EventTimeline` that's a share, defaulting to a locale-aware percent. On `CalendarStrip` it's the day's value in the hover/focus readout — so it lives on the interactive entry only. The static `CalendarStrip` summary counts days — `Active 3 of 28 days over 4 weeks.` — and a count of days is not a number `format` gets to restyle. Date and time *strings* are a separate prop, **`dateFormat`**, taking `Intl.DateTimeFormatOptions` or a `(date) => string` function. It lives on the interactive entries (`@microcharts/react/calendar-strip/interactive`, `@microcharts/react/event-timeline/interactive`), which are the entries that render a spoken or hovered date at all — `locale` applies to it the same way. ```tsx import { CalendarStrip } from "@microcharts/react/calendar-strip/interactive"; <CalendarStrip data={days} dateFormat={{ month: "short", day: "numeric" }} locale="de-DE" />; ``` When you pass options (rather than a function), the formatter defaults to `timeZone: "UTC"`, so the same input renders identically in any host timezone — a chart never shifts a day because the viewer is in a different region. Your options spread after that default, so `{ timeZone: "America/New_York" }` overrides it deliberately. A `(date) => string` function bypasses the default entirely and owns its own timezone handling. # Full chart libraries (/docs/full-chart-libraries) [Recharts](https://recharts.org) and [Chart.js](https://www.chartjs.org) are full chart libraries. They draw surfaces that are mostly chart: scales, legends, tooltips, plugins, dashboard layouts. microcharts draws a word-sized mark *inside* a surface you already have — a sentence, a table cell, a KPI, a streamed reply — where a full chart library would be too heavy and too loud. We are not a substitute for either. Read [When to use microcharts](/docs/when-to-use) for the product decision; this page pins the size numbers so they stay honest. ## Side by side [#side-by-side] | | Full library (Recharts, Chart.js, …) | microcharts | | -------------------- | ------------------------------------ | ----------------------------------------------- | | Surface | The chart *is* the panel | The chart sits in prose / cell / KPI | | Chrome | Axes, legends, tooltips, brush | None by design | | Typical budget | Tens to hundreds of kB | <SizeMarketing /> | | Runtime dependencies | Real dependency trees | Zero (`dependencies: {}`; React is a peer) | | Server Components | Usually a client chart runtime | Default export is hook-free SVG, zero client JS | | Accessible name | You wire it (plugins, tables, aria) | `role="img"` + summary from the data by default | A product can use both when it needs both jobs. ## Recharts [#recharts] Recharts is a strong default for React dashboards: composable `<LineChart>`, axes, tooltip, responsive container. Orientation numbers (not “smaller wins for every app”): <VsRechartsTable /> **Reach for Recharts** when the page is mostly chart — ticks, legends, brush, or a familiar Recharts tree. **Reach for microcharts** when the mark must live in a sentence, a cell, or an RSC with nothing to hydrate. ```tsx // Recharts — full surface import { LineChart, Line, XAxis, YAxis, Tooltip, ResponsiveContainer } from "recharts"; <ResponsiveContainer width="100%" height={240}> <LineChart data={rows}> <XAxis dataKey="t" /> <YAxis /> <Tooltip /> <Line type="monotone" dataKey="v" /> </LineChart> </ResponsiveContainer>; // microcharts — word-sized mark import { Sparkline } from "@microcharts/react/sparkline"; <span className="mc-inline"> <Sparkline data={[3, 5, 4, 8, 6, 9]} dots="none" summary={false} width={64} height={16} /> </span>; ``` ## Chart.js [#chartjs] Chart.js is Canvas-first, with a large plugin and config ecosystem. In React it is usually wrapped by `react-chartjs-2`. That stack is for dashboard and report canvases — not for a mark in a table cell. <VsChartJsTable /> **Reach for Chart.js** when you need Canvas, existing Chart.js configs or plugins, or dense series on a chart panel. **Reach for microcharts** when you need inline SVG, accessible-by-default summaries, or static RSC output. Canvas charts need an explicit accessibility path (hidden table, aria, plugins). microcharts makes the accessible name the default — see [Accessibility](/docs/accessibility). That is not a claim that Chart.js cannot be made accessible. ## What this page is not saying [#what-this-page-is-not-saying] * Not “faster than Recharts for dashboards” * Not “Chart.js, but lighter, for the same job” * Gzip figures here are orientation, not a scoreboard If the job is a full chart, pick a full library. If the job is a word-sized mark, pick microcharts — or add it alongside the library you already trust. ## Next [#next] * [When to use microcharts](/docs/when-to-use) * [microcharts vs Recharts](/docs/vs-recharts) · [microcharts vs Chart.js](/docs/vs-chartjs) — the per-library detail * [React sparklines](/docs/react-sparklines) * [Inline charts](/docs/inline-charts) * [Performance](/docs/performance) * [Introduction](/docs) # Introduction (/docs) microcharts is a set of tiny, handcrafted charts for React — **made for AI first, and for the people reading what it writes**. The grammar is small and predictable enough for a model to emit correctly mid-sentence, and every chart describes itself in words, so a chart an LLM streams into a chat reply, a document, or a generated slide is one a person can read and trust. They're built to sit *inside* an interface — in a sentence, a table cell, a KPI card, a tab header, a streamed reply — where a full chart library would be too heavy and too loud. One quiet signal, read at a glance. Prefer [Set up with AI](/docs/quickstart#set-up-with-an-ai-agent) — paste one prompt and an agent installs the package, imports the stylesheet, and verifies with a first chart. Or install manually (both steps are required): The other half of manual setup is one stylesheet import at your app root — see the [Quickstart](/docs/quickstart#set-up-manually). Every chart renders from `data` alone, ships as pure SVG with **zero runtime dependencies**, and carries an accessible description generated from the data itself — the same properties that make it safe for a model to write are the ones that make it pleasant for a human to use. ```tsx `" > <Sparkline data="[3, 5, 4, 8, 6, 9]" width="120" height="32" title="Weekly revenue" /> ``` ## Why microcharts [#why-microcharts] * **AI-native, by design.** A chart is plain `data` plus generated words, so a model can emit one mid-sentence and read one back — [chat streams, agents, and tool output](/docs/ai) are the primary homes, not an afterthought. One grammar across 106 types means an LLM that has seen one chart can write them all. * **Zero dependencies.** No chart engine, no D3 — just SVG. CI-enforced, forever. * **Server-component safe.** Static charts are hook-free and listener-free; they render to HTML with zero client JavaScript, and add interactivity only from a separate `/interactive` subpath — where one contract covers the catalog: hover, roving arrow keys, touch scrub, and click-to-pin, read back through `onActive` / `onSelect`. Single-unit charts have nothing to rove between and take `onSelect` alone. * **Accessible by default.** Each chart is an `img` with a natural-language summary built from your data — nothing to remember, nothing to drift. * **Tiny.** **\~2–7 kB interactive · \~1–4 kB static** gzip each, imported from their own subpath and budget-gated in CI. ## One catalog, one grammar [#one-catalog-one-grammar] The library ships a full catalog of chart types, grouped by the question each one answers. `data` alone always renders something correct, and a prop name means the same thing on every chart — so you pick by the *decision* you need read, not by fighting an options bag. From sparklines to bump charts, funnels, honeycombs, and calendar strips — a small sample of what ships: A representative slice of the catalog spans trends, comparisons, distributions, and status — see every chart type at [/docs/charts](/docs/charts). Browse them all on the [All charts](/docs/charts) page, which files every type under the question it answers — start from what you need someone to see, and land on the chart. ## Where they live [#where-they-live] The point of a word-sized chart is that it belongs *in* your interface, not in a dashboard off to the side. And because it's plain SVG that renders from `data` alone, "interface" isn't limited to a browser tab: * **In your product** — a trend in a table cell, a KPI card, a tab header, a dense dashboard, where a full chart engine would be too heavy and too loud. * **In a report or slide** — a figure in a rendered PDF or deck, the same markup that drops into a table cell, with nothing to export. * **In your docs** — inline in Markdown, next to the sentence that explains it. The charts on this very page are rendered exactly that way — MDX in, live SVG out. * **In an AI reply** — streamed mid-sentence by a model, since every chart is plain data plus generated words. [AI-native](/docs/ai) shows a live stream doing exactly that. Here's the same chart doing its job in four of those homes: [Composition](/docs/composition) has the exact placement recipe for each surface — a table cell, a KPI card, a tab, or inline in a sentence. Unsure whether this library or a full chart library fits? [When to use microcharts](/docs/when-to-use). Ready to render one? The [Quickstart](/docs/quickstart) gets you from install to a live chart in minutes. ## FAQ [#faq] ### What are micro charts? [#what-are-micro-charts] Micro charts — also called sparklines, tiny charts, or inline charts — are small, word-sized data visualizations: a trend line, bar, or dot that fits inside a sentence, table cell, or KPI card without axes or legends. They answer one question at a glance in the space of a word, where a full chart would be too heavy and too loud. ### What is microcharts? [#what-is-microcharts] microcharts is a React chart library of word-sized SVG charts — sparklines, bars, bullets, and the rest of the catalog — built to sit inside sentences, table cells, KPI cards, and AI replies. Zero runtime dependencies, accessible by default, and server-component safe. ### How is microcharts different from Recharts or Chart.js? [#how-is-microcharts-different-from-recharts-or-chartjs] Those are full chart libraries for surfaces that are mostly chart. microcharts is built to sit *inside* an interface — word-sized SVG marks where a full chart library would be too heavy and too loud. One chart per subpath, typically **\~2–7 kB interactive · \~1–4 kB static** gzip, no axes or legends, static entries with **zero client JavaScript** from an RSC. We are not a replacement; see [When to use](/docs/when-to-use) and [Full chart libraries](/docs/full-chart-libraries), or the measured per-library pages: [vs Recharts](/docs/vs-recharts), [vs Chart.js](/docs/vs-chartjs), [vs react-sparklines](/docs/vs-react-sparklines), [vs MUI X Sparkline](/docs/vs-mui-x-sparkline), and [vs visx](/docs/vs-visx). ### Are microcharts accessible? [#are-microcharts-accessible] Yes. Every chart is `role="img"` with a natural-language summary generated from the data. Interactive entries add keyboard navigation and a polite live region. Direction and state are never color-alone — see [Accessibility](/docs/accessibility). ### Do static microcharts need client JavaScript? [#do-static-microcharts-need-client-javascript] No. Default exports are hook-free pure SVG — RSC-safe with zero client JS. Import the matching `/interactive` subpath only when you need hover, keyboard, touch, or selection. ### Why is there no pie chart, gauge, or waffle? [#why-is-there-no-pie-chart-gauge-or-waffle] They fail at word size: pie angles are unreadable in a table cell, a needle gauge spends its pixels on chrome, a waffle doesn't fit in a word. Each refusal has an honest in-catalog replacement — [SegmentedBar](/docs/charts/segmented-bar) for pie, [Bullet](/docs/charts/bullet) for gauges, [IconArray](/docs/charts/icon-array) for waffle. The reasoning lives in [Design notes](/docs/design-notes) and [When to use](/docs/when-to-use). ### Why does my first chart render unstyled, or with serif labels? [#why-does-my-first-chart-render-unstyled-or-with-serif-labels] Almost always one of two setup steps: the stylesheet isn't imported at your app root (`import "@microcharts/react/styles.css"`, once), or the surrounding page never sets a `font-family`, so SVG text falls back to a serif — set `--mc-font` or give the page a font. Both are covered in the [Quickstart](/docs/quickstart#set-up-manually). ### Can I match the charts to my brand color? [#can-i-match-the-charts-to-my-brand-color] Yes — pass one accent to `defineTheme` and it derives a color-blind-safe categorical palette plus hand-tuned-style dark twins, in OKLCH, with zero dependencies; or set the `--mc-*` tokens directly. The one thing a theme can never change is what the data means: positive and negative keep their hues on every accent and preset. See [Theming](/docs/theming). ### How do I propose a new chart type? [#how-do-i-propose-a-new-chart-type] Open an issue first. A new type must clear the admission bar: a unique data story the catalog can't already answer, one honest encoding channel, and readable at ≤ 200×60 px without training. It's a high bar on purpose — every shipped chart clears it, and [CONTRIBUTING.md](https://github.com/ganapativs/microcharts/blob/main/CONTRIBUTING.md) walks through the rest. > microcharts is tested and ready to use in production — but it hasn't been battle-tested across every stack and edge yet, so you may hit the occasional rough edge. When you do, tell us: bug reports and feature requests on [GitHub](https://github.com/ganapativs/microcharts/issues) are how it keeps getting sharper. ## Made by [#made-by] microcharts is designed and built by [Ganapati V S](https://meetguns.com) — [@ganapativs](https://x.com/ganapativs) on X, [ganapativs](https://github.com/ganapativs) on GitHub. It's free and open source under the MIT license; the code lives on [GitHub](https://github.com/ganapativs/microcharts), where issues, ideas, and stars are all welcome. Want to contribute? [CONTRIBUTING.md](https://github.com/ganapativs/microcharts/blob/main/CONTRIBUTING.md) covers the dev setup, the non-negotiables, and what a PR needs to ship. # Inline charts (/docs/inline-charts) Word-sized charts sit *inside* the interface you already ship: a trend in a table cell, a sparkline after a number, a bullet in a KPI, a mark in a streamed reply — not a chart page you navigate to. That is what `@microcharts/react` is built for. Full dashboard canvases belong with [full chart libraries](/docs/full-chart-libraries). <CatalogTotal /> types, one grammar. Size band: <SizeMarketing />. Static entries ship **zero client JavaScript** from a React Server Component. Accessible by default — each chart is an `img` with a summary generated from the data. ## The surfaces [#the-surfaces] ### In a sentence [#in-a-sentence] Wrap with `mc-inline`, drop endpoint dots, mark decorative when the sentence already carries the meaning: ```tsx p95 latency this week{" "} <span className="mc-inline"> <Sparkline data={latency} dots="none" summary={false} width={64} height={16} /> </span>{" "} — trending down. </p>`" > <p className="max-w-md text-[0.95rem] leading-relaxed"> {"p95 latency this week "} <span className="mc-inline"> <Sparkline data="[48, 45, 44, 40, 38, 36, 33, 31]" dots="none" summary="false" width="64" height="16" /> </span> {" — trending down."} </p> ``` ### In a table cell [#in-a-table-cell] ```tsx <table className="w-full max-w-sm text-sm tabular-nums"> <thead className="sr-only"> <tr> <th scope="col"> Service </th> <th scope="col"> Trend </th> <th scope="col"> Now </th> </tr> </thead> <tbody> <tr className="border-b border-hairline"> <td className="py-1.5 pr-3 text-fd-muted-foreground"> checkout </td> <td className="py-1.5"> <Sparkline data="[40, 38, 36, 34, 32, 31, 30, 31]" width="72" height="16" dots="none" summary="false" /> </td> <td className="py-1.5 pl-3 text-right"> 31ms </td> </tr> <tr> <td className="py-1.5 pr-3 text-fd-muted-foreground"> search </td> <td className="py-1.5"> <Sparkline data="[80, 78, 82, 79, 81, 80, 79, 78]" width="72" height="16" dots="none" summary="false" /> </td> <td className="py-1.5 pl-3 text-right"> 78ms </td> </tr> </tbody> </table> ``` ### In a KPI / tab [#in-a-kpi--tab] Attainment and cadence marks stay tiny on purpose — [Bullet](/docs/charts/bullet), [Progress](/docs/charts/progress), [Delta](/docs/charts/delta), [StatusDot](/docs/charts/status-dot). Exact placement recipes: [Composition](/docs/composition). Broader fit: [When to use microcharts](/docs/when-to-use). ## Server-component safe [#server-component-safe] Static charts are hook-free and listener-free — they render to HTML with zero client JavaScript. Add interactivity only from a separate `/interactive` subpath. ```tsx // Server Component — no "use client", nothing to hydrate for the chart import { Sparkline } from "@microcharts/react/sparkline"; export default function Row() { return <Sparkline data={[3, 5, 4, 8, 6, 9]} title="Weekly revenue" />; } ``` ## Start here [#start-here] * [When to use microcharts](/docs/when-to-use) * [React sparklines](/docs/react-sparklines) * [Introduction](/docs) — grammar and catalog * [Quickstart](/docs/quickstart) # Performance (/docs/performance) Performance isn't a marketing line here — it's a build gate. Every figure on this page is produced by a command you can run yourself, checked against the shipped `dist` in CI, and regenerated on every release so it can never drift from reality. ## Size [#size] Each chart is imported from its own subpath, so a bundle ships only the charts it uses — importing `Sparkline` never pulls in the other 105. Sizes are gzip, measured by `pnpm size` and gated: a chart that grows past its budget fails the build. The interactive catalog lands between **1.88 kB and 6.64 kB** gzip, with a **median of 5.03 kB** — hover, roving keyboard focus, select-to-pin, touch scrub, and live announcements from the `/interactive` subpath. The static twin lands between **0.97 kB and 3.99 kB**, with a **median of 2.6 kB** — pure SVG, zero client JavaScript. A page pays for interactivity only where it actually uses it. About 0.5 kB of the interactive delta is the shared picker kernel, which the per-subpath gate measures standalone in every entry; a page using several interactive charts bundles it once. Twenty-five charts sit above the 3 kB static reference line, none of them by more than 0.99 kB. Sparkline, the most configurable primitive in the set, is the largest; most of the rest are value-series charts that host annotations (ChangePoint, WinProbWorm, ForecastCone, DualSparkline, BurnChart, SpreadBand, RetentionCurve, ControlStrip, QueueDepth, SparkBar, EnsembleGhosts, NetFlow, Slope), plus Station Glyph, PercentileLadder, ShiftHistogram, StackedArea, ABStrips, PolarClock, Constellation, Dumbbell, CyclePlot, Waterfall, and TapeGauge. The annotation hosts carry a small shared walker that resolves `Threshold`, `Marker`, and the rest against the chart's scale — you pay for it only on those charts, and each is still smaller than a single icon font. ### Splitting the stylesheet [#splitting-the-stylesheet] `@microcharts/react/styles.css` is one artifact for the whole catalog, and importing it once is the right default — it is small, it caches, and it never grows with the number of charts you use. If you ship exactly one or two charts and want the rules for the rest gone, there is an opt-in split: `@microcharts/react/styles/core.css` carries everything shared, and `@microcharts/react/styles/<slug>.css` carries the rules specific to a single chart. Only the charts with chart-specific CSS have a file; the rest need `core.css` alone. ```ts import "@microcharts/react/styles/core.css"; import "@microcharts/react/styles/sparkline.css"; ``` `core.css` plus the slugs you import is equivalent to the matching subset of `styles.css` — same rules, same `@layer` membership, same cascade order — so the split is a byte trade, never a behavior change. Import one or the other, not both. ## Server rendering [#server-rendering] Static charts are hook-free and listener-free, so a React Server Component renders them to plain SVG on the server — **zero client JavaScript** reaches the browser. Throughput, measured by `pnpm bench` rendering *N* sparklines to an SVG string: A table of **500 sparklines becomes HTML in under six milliseconds**, streams as part of the document, and ships nothing to hydrate. Across all 106 chart types the median **static** SSR render is about **0.03 ms per chart** — the heavier expressive and frontier instruments cost more geometry, the simple strips cost almost nothing. The core summary kernel is just as cheap: `describeSeries`, which writes every chart's accessible sentence, runs at roughly **892,000 calls per second** (24-point series, measured by `pnpm bench`), so accessibility is never the thing that slows a render down. ## Why it's fast [#why-its-fast] The speed isn't a trick — it's the absence of one. * **No chart engine.** No D3, no layout runtime, no virtual DOM diff for a static chart. Scales, paths, and stats are a few hundred lines of pure functions, and the output is a handful of SVG nodes — typically six or fewer per chart. * **Zero runtime dependencies.** `dependencies: {}`, enforced by CI, forever. Nothing to resolve, nothing to audit, nothing to bloat a lockfile. * **Integer geometry, crisp marks.** Coordinates are rounded at generation and rectilinear marks use `shape-rendering: crispEdges`, so the browser does less work rasterising them. * **One stylesheet, one cascade layer.** Theming is CSS custom properties in a low-specificity `@layer`, not inline styles recomputed per instance. * **A scrub costs one render per unit crossed, not one per pointer move.** Interactive entries put a single listener on the wrapper and resolve the unit with pure math, then bail out when the unit hasn't changed — so a sweep across a 24-point Sparkline re-renders at most 24 times no matter how many pointer events the browser delivers. ### Re-rendering many charts [#re-rendering-many-charts] Static entries are hook-free — that's what keeps them RSC-safe — so they can't memoise internally: a parent re-render re-runs each chart's geometry. That's cheap per chart, but it adds up in a table of hundreds. If you render many charts inside a component that re-renders for unrelated reasons, wrap them and keep `data` referentially stable: ```tsx const Spark = memo(Sparkline); ``` The catch is that `memo` only helps when props are actually stable — pass a fresh array literal (`data={[1, 2, 3]}`) or JSX children and it misses every time, and you pay the comparison on top of the render you were going to do anyway. Hoist the array, or skip it. We don't ship `memo` on the charts themselves for exactly that reason: it would tax the common case to speed up a specific one, and it's your call, not ours. ## Honest caveats [#honest-caveats] * **The bench is one process, and that used to bite.** Measuring 106 components in sequence let earlier charts leave the later ones cold, and a median over windows short enough for one GC pause produced bimodal numbers — the same chart read 140 and 35 rows/ms on consecutive runs of identical code. `pnpm bench` now warms each component immediately before timing it and reports the fastest window, since GC and scheduler noise only ever slow a window down. Every chart clears its floor; if one stops, `pnpm bench` exits non-zero and names it. * **Interactive entries do ship JavaScript.** The `/interactive` subpath adds a client component and a small set of listeners on the wrapper — pointer, keyboard, and touch — plus the shared picker kernel that resolves them to a unit with pure math. There is still never a listener per data point, so a 30-point chart and a 365-cell grid cost the same. It's tiny, but it isn't zero — reach for the static entry unless a chart genuinely needs hover, keyboard, selection, or live announcements. * **These numbers are one machine, one Node.** They measure *relative* cost honestly and reproduce on your hardware; treat them as a floor to reproduce, not an absolute to quote. ## Reproduce it [#reproduce-it] Every figure above regenerates from the repo. Nothing is hand-keyed — the docs read the measured output directly. ```bash git clone https://github.com/ganapativs/microcharts pnpm install pnpm build # build dist the numbers are measured against pnpm bench && node scripts/sync-bench.mjs # SSR throughput → bench-summary.json node scripts/sync-sizes.mjs # gzip budgets → chart-sizes.json ``` CI runs `--check` on both synced files, so a stale number fails the build the same way a failing test does. # Quickstart (/docs/quickstart) ## Set up [#set-up] Prefer an agent — paste the prompt once. It installs the package, imports the stylesheet at your app root, records the conventions in your agent-rules file, and verifies with a first chart. Or do the two steps yourself under [Set up manually](#set-up-manually). ### Set up with an AI agent [#set-up-with-an-ai-agent] Hand the prompt below to your coding agent — **Cursor, Claude Code, GitHub Copilot, Codex**, or any model, large or small. Works on a fresh repo or an existing one. It's also served verbatim at [`/agent-setup.md`](/agent-setup.md). <div className="agent-prompt"> ```md title="Paste into your agent" Set up **@microcharts/react** in this repo — word-sized, zero-dependency React charts (React 18 or 19 peer, ESM-only). Complete every step in order; don't stop to ask. ## 1 · Install - If this repo is not already a React 18/19 app, scaffold one first (Vite `react-ts` or Next.js), then continue. - Install `@microcharts/react` with this repo's package manager. - Import the stylesheet once at the app root (both package + stylesheet are required): - Next.js App Router: `app/layout.tsx` - Next.js Pages Router: `pages/_app.tsx` - Vite / other React apps: the entry file (e.g. `src/main.tsx`) `import "@microcharts/react/styles.css"` - Charts inherit the page font. If labels look like a serif fallback, set `:root { --mc-font: system-ui, sans-serif; }`. ## 2 · Docs — fetch small, on demand - https://microcharts.dev/llms.txt — index: every chart + guide links. Read this now. - https://microcharts.dev/catalog.json — full API. Do **not** read the whole file. Find the chart by `slug`, then use `sharedProps` + that chart's `props`. If the chart has `sharedInteractive` / the document has `howToRead`, follow those; otherwise use the chart's `.md` for interactive callbacks. Never invent props. - https://microcharts.dev/docs/charts/<slug>.md — one chart's page (import path, edge cases). Fetch only for charts you use — pick the slug from the index. - https://microcharts.dev/docs/quickstart.md — grammar + interactive contract, if you need more than the rules below. If you can't fetch URLs, skip this step — the rules below are enough to render a first chart correctly. ## 3 · Record the conventions Append the rules below as a `## microcharts` section in `AGENTS.md` (create the file if missing — Cursor, Copilot, and Codex read it). If this repo uses Claude Code, mirror it: `ln -s AGENTS.md CLAUDE.md` on macOS/Linux, or copy the section into `CLAUDE.md` on Windows. - One chart = one subpath import, e.g. `import { Sparkline } from "@microcharts/react/sparkline"`. The default export is static — RSC-safe, zero client JS. Add `/interactive` only when hover, keyboard, touch, or selection is needed. That entry is a client component: in Next.js App Router, import it from a `"use client"` file. WindBarb is static-only. - `data` alone always renders; single-value charts take `value` instead. Shared prop names mean the same thing everywhere — see `sharedProps` in `/catalog.json`. Chart-specific props and callbacks live on the chart's catalog entry and its `.md` page; don't memorize them. - Interactive entries share one contract: hover/arrows activate; click/tap/Enter/Space select; Escape clears. Prefer each chart's `sharedInteractive` list when present (lean scalars may take only `onSelect`; MinimapStrip uses `onWindowChange` in chart `props`). For entrance motion: pass `animate` and import `@microcharts/react/motion` once on the client. - `null`, `NaN`, or non-finite values in `data` are gaps, never zeros. - Accessibility is automatic (`role="img"` + a generated summary). Inline in a sentence: wrap in `<span className="mc-inline">` and pass `summary={false}`. - Theme with `--mc-*` or `data-mc-theme` (omit for default), or `defineTheme` from `@microcharts/react/theme`. Charts paint no background. Prefer tokens; `color` / categorical `colors[]` are valid when the chart's docs say so. - Annotations are children: `Threshold`, `TargetZone`, `Marker`, `Callout` from `@microcharts/react/annotations`. - Never add another charting dependency. No pie or gauge — use `Bullet`, `SegmentedBar`, or `MicroDonut`. ## 4 · Verify Render `<Sparkline data={[3, 5, 4, 8, 6, 9]} title="Weekly revenue" />` in a real page, then run the dev server or build. Self-check: - Chart missing or unstyled → the styles.css import isn't at the root (step 1). - Labels render in a serif font → set `--mc-font` (step 1). Finish with a short report: the installed version, the file importing styles.css, the file holding the conventions, and the page rendering the test chart. ``` <AgentPromptCopy /> </div> The prompt fetches small, targeted files — the [`/llms.txt`](/llms.txt) index first, then one chart's `.md` page at a time — so it stays inside the context window of smaller models and works from today's real API instead of a memorized guess. The rules are inlined too, so it still works when the agent can't reach the network. ### Set up manually [#set-up-manually] Two steps, once, at your app root — package plus stylesheet. Both are required, and both fit in the next minute. **1 · Install.** React 18 or 19 is a peer dependency; there are no other runtime dependencies. **2 · Import the stylesheet once** at the root of your app — it carries every theming token and chart style in a low-specificity cascade layer, so your own styles always win. Where "root" means depends on your framework — anywhere that runs once, before any chart renders: #### Next.js ```tsx title="app/layout.tsx" import "@microcharts/react/styles.css"; ``` #### Vite / CRA / other React apps ```tsx title="src/main.tsx" import "@microcharts/react/styles.css"; ``` > Charts **inherit your page's font**. If the surrounding page never sets a `font-family` (some minimal starters and sandboxes don't), SVG text falls back to a serif and labels look wrong — give your page a font, or set one just for charts: ```css :root { --mc-font: system-ui, sans-serif; } ``` Full detail — why it inherits, and per-scope fonting — in [Theming](/docs/theming#the-font). ## Your first chart [#your-first-chart] Every series chart renders from `data` alone — single-value charts take `value`. Either way it works in a React Server Component with **zero client JavaScript** — it's pure SVG, and its accessible name is generated from the data. ```tsx ; }`" > <Sparkline data="[3, 5, 4, 8, 6, 9]" width="120" height="32" title="Weekly revenue" /> ``` ### Try it live [#try-it-live] No install needed to feel it out. Open a full Vite + React app with the package installed in StackBlitz — static and interactive charts, inline and block, four themes, running in your browser. <StackBlitzSandbox /> ## The shared grammar [#the-shared-grammar] One idea runs through the whole catalog: **the same prop name means the same thing on every chart.** Learn these once and they transfer everywhere — a new chart type is a new data shape, never a new vocabulary. The data prop alone always renders something correct; everything else is opt-in. | Prop | Type | What it does | | ---------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `data` | `(number \| null)[] \| per-chart shape` | The series. `null` / `NaN` are gaps, never zeros. The one required prop; each chart documents its own shape when it isn't a plain number array. | | `domain` | `[min, max]` | Fix the value range instead of auto-fitting — see [Formatting & scale](/docs/formatting#scale-the-domain-decision). | | `color` | `string` | Mark color: any CSS color or a token (`"var(--mc-accent)"`). Semantic tokens keep their meaning — see [Theming](/docs/theming). | | `title` | `string` | Names the chart — an SVG `<title>`, so it becomes the accessible name and the hover tooltip, not visible text. | | `summary` | `string \| false` | Override the auto-generated accessible sentence, or pass `false` to mark the chart decorative — see [Accessibility](/docs/accessibility). | | `format` | `Intl.NumberFormatOptions \| (n) => string` | How numbers render in labels and summaries — see [Formatting & scale](/docs/formatting). | | `positive` | `"up" \| "down"` | Which direction is good, so color and arrows point the honest way (lower latency is `"down"`). | | `label` | *per chart* | A short direct label next to the mark, in a reserved gutter — never an axis or legend. | | `dots` | *per chart* | Which individual points to emphasize (e.g. `"minmax"` on a line). | Not every prop applies to every chart — a bar chart has no `dots`, and the single-value charts take `value` rather than `data` — but wherever a concept exists, its prop name and meaning are always these. Each one has a deeper home: [Formatting & scale](/docs/formatting) owns `format` and `domain`, [Theming](/docs/theming) owns `color`, and [Accessibility](/docs/accessibility) owns `summary`. Alongside the grammar sit the layout props — `className` and `style` on every chart, plus `width` and `height` on the charts whose geometry is sized that way (the fixed-glyph ones size from `style` or their own `size` / `cell` knob) and `id`, which opts into `<title>`/`<desc>` + `aria-labelledby` naming; see [Sizing](/docs/sizing). The i18n props are `locale` (BCP-47, for number and date formatting) and `strings` (the summary/label templates), plus `seriesStrings` on the multi-series charts — see [Accessibility](/docs/accessibility#internationalization-and-rtl). Everything else is specific to a chart's own shape and listed in the prop table on its page. To place charts in real UI — or render several on one shared scale with `SparkGroup` — see [Composition](/docs/composition). Annotations are children: [`Threshold`, `TargetZone`, `Marker`, `Callout`](/docs/annotations). ## Add interactivity [#add-interactivity] Need hover, keyboard navigation, touch, or live announcements? Import the same chart from its `/interactive` entry. The rendered output and the accessible name are identical — the interactive entry composes its static twin rather than re-implementing it — and it **adds** props rather than changing any: the interaction callbacks below, plus `animate`, `strings` on the charts whose static entry doesn't take it, `live` on the single-value charts, and `onWindowChange` on MinimapStrip. The interactive entry **is** a client component: in a Next.js App Router page, render it from a file with `"use client"` at the top (or anywhere inside one). ```tsx "use client"; import { Sparkline } from "@microcharts/react/sparkline/interactive"; <Sparkline data={[3, 5, 4, 8, 6, 9]} title="Weekly revenue" />; ``` ### One interaction contract [#one-interaction-contract] Every interactive chart behaves the same way, so you learn it once. Hover or arrow keys make a unit **active**; a click, tap, **Enter**, or **Space** **selects** it and pins the readout so it survives blur. **Escape** clears, **Home**/**End** jump to the ends, and arrows rove in both axes (←/↑ previous, →/↓ next). On touch, a tap pins and a drag scrubs. What a "unit" is depends on the chart — a point, a bar, a day cell, a segment — and each chart's page names its own. | Prop | Type | What it does | | ---------------------- | ------------------------------------- | ------------------------------------------------------------------------------------ | | `onActive` | `(datum: MicroDatum \| null) => void` | The active unit changed (pointer or keyboard). `null` when the chart clears. | | `onSelect` | `(datum: MicroDatum \| null) => void` | A unit was selected or unselected — click, tap, `Enter`, `Space`, `Escape`. | | `selectedIndex` | `number \| null` | Control the selection yourself. | | `defaultSelectedIndex` | `number \| null` | Seed the selection once, then let the chart own it. | | `readout` | `boolean` | Show the floating value chip on hover (default `true`). `false` hides only the chip. | `MicroDatum` is `{ index, value, label?, formatted? }`. Two of the fields carry the value in different forms, so you pick the one that fits: **`value`** is the raw primary number — compute with it (`null` when the unit encodes nothing); **`formatted`** is the ready-to-display string the chart's own readout would show, built with your `format`/`locale` — render it. For a plain chart that's just the value (`"$0.53"`); for a two-part unit it's the whole readout (`"48 → 68 (up 42%)"`). `index` identifies the unit (point, bar, cell, segment…), and `label` is its human name where one exists (`"Berlin"`, `"Checkout"`). Same shape on every chart and both callbacks. Pair the two to lift the value out of the chart. Set `readout={false}` to keep the hover crosshair but suppress the in-chart chip, and read `datum.formatted` in `onActive` to render that value wherever you like — a KPI number, a sentence, a table cell — without re-deriving `format`/`locale` yourself: ```tsx const [spend, setSpend] = useState("$0.53"); <Sparkline data={cost} format="$,.2f" readout={false} onActive={(d) => d && setSpend(d.formatted!)} />; ``` Scalar charts with a single unit — Delta, Progress, StatusDot, Bullet and the rest — take `onSelect` only; there's nothing to rove between. Fifteen of them also take `live` (default `true`): as the value updates, the new reading is announced through a polite live region, throttled so a streaming number never spams a screen reader. Not all of them do — Bullet's only interaction prop is `onSelect` — so check the chart's own page. Two charts opt out of the picker on purpose: `MinimapStrip` is a range slider with its own `onWindowChange([lo, hi])`, and `TokenConfidence` moves real focus through inline text spans. Full detail, including the live-region behavior, is on [Accessibility](/docs/accessibility#one-interaction-contract). ## Animate on mount (optional) [#animate-on-mount-optional] Interactive entries also take an `animate` prop — the chart draws on instead of appearing instantly. It's off by default, and inert on the server and on hydrated server HTML, so it never fights SSR or flashes over painted content; a fresh client-side mount is what plays it. Wire the engine once, client-side, then opt in per chart: ```tsx "use client"; import "@microcharts/react/motion"; // once, client-side import { Sparkline } from "@microcharts/react/sparkline/interactive"; <Sparkline data={[3, 5, 4, 8, 6, 9]} title="Weekly revenue" animate />; ``` `prefers-reduced-motion` wins unconditionally — a reader who asked for less motion gets the finished chart, never the entrance. ## Import paths [#import-paths] Import each chart from its own subpath so you only ship what you use. Nearly every chart follows the same two-entry pattern — a static default and an `/interactive` twin (WindBarb is the lone static-only exception): | Chart | Static | Interactive | | ------------ | ---------------------------------- | ---------------------------------------------- | | Sparkline | `@microcharts/react/sparkline` | `@microcharts/react/sparkline/interactive` | | SparkBar | `@microcharts/react/sparkbar` | `@microcharts/react/sparkbar/interactive` | | Delta | `@microcharts/react/delta` | `@microcharts/react/delta/interactive` | | Bullet | `@microcharts/react/bullet` | `@microcharts/react/bullet/interactive` | | ActivityGrid | `@microcharts/react/activity-grid` | `@microcharts/react/activity-grid/interactive` | Every other chart uses the same shape (WindBarb ships static-only, with no `/interactive` twin) — see [All charts](/docs/charts) for the full catalog, each page listing its own import path and props. ## Compatibility [#compatibility] * **React 18 or 19** as a peer dependency — no other runtime dependencies, ever (`dependencies: {}`, CI-enforced). * **ESM-only.** The package ships `"type": "module"`; there's no CommonJS build. * **Server-component and SSR-safe.** Static entries are hook-free and listener-free, so they render to plain SVG on the server with zero client JavaScript — no `"use client"` needed unless you import from `/interactive`. * **Browser floor: evergreen, ES2022.** That includes Safari from version 16.4 — a couple of ES2022 array methods used internally crash on older Safari, so that's the practical minimum, not just a `tsconfig` setting. # React sparklines (/docs/react-sparklines) A **sparkline** is a trend small enough to sit in a sentence: direction and shape at a glance — not a dashboard panel with axes. In React, that means a word-sized SVG mark next to a number or inside a table cell, where a full chart library would be too heavy and too loud. This page covers that mark in `@microcharts/react`. Props, variants, and edge cases live on [Sparkline](/docs/charts/sparkline). ```tsx <Sparkline data="[3, 5, 4, 8, 6, 9]" width="120" height="32" title="Weekly revenue" /> ``` ## Install [#install] Both steps are required — package and stylesheet: ```tsx import { Sparkline } from "@microcharts/react/sparkline"; import "@microcharts/react/styles.css"; // once, at the app root <Sparkline data={[3, 5, 4, 8, 6, 9]} title="Weekly revenue" />; ``` Measured size for this chart: <ChartSize slug="sparkline" /> gzip (CI-enforced). Catalog-wide band: <SizeMarketing />. The default export is static — RSC-safe, zero client JavaScript. Add `@microcharts/react/sparkline/interactive` only when hover, keyboard, touch, or selection is needed. ## Where it sits [#where-it-sits] Same component in four homes — product UI, report, docs, and an AI reply: Placement recipes: [Composition](/docs/composition). When this library fits vs a full chart library: [When to use microcharts](/docs/when-to-use). ## About `react-sparklines` [#about-react-sparklines] Many searches still land on [`react-sparklines`](https://www.npmjs.com/package/react-sparklines) (Boris Yankov) — about **250k downloads** in the week ending **2026-07-21**, last npm publish **2017-07-27** (`1.7.0`). Same visual idea; a different era of React (class-component patterns, `prop-types`, no generated accessible summary, not aimed at RSC). The measured side-by-side lives at [microcharts vs react-sparklines](/docs/vs-react-sparklines). microcharts is not that package rewritten. It is a word-sized catalog — <CatalogTotal /> types, one grammar — where Sparkline is one chart: `data` alone renders, accessible by default (`role="img"` + a summary from the data), static RSC entry, **zero runtime dependencies**. If `react-sparklines` still fits your stack, that is a valid choice. If you want the contract above, start here. ## When not to use a sparkline [#when-not-to-use-a-sparkline] * Exact category comparison → [MiniBar](/docs/charts/mini-bar) or [SparkBar](/docs/charts/sparkbar) * Value against a target → [Bullet](/docs/charts/bullet) * Part-to-whole → [SegmentedBar](/docs/charts/segmented-bar) or [MicroDonut](/docs/charts/micro-donut) * Full axes, legend, brush, zoom → a [full chart library](/docs/full-chart-libraries) ## Related marks [#related-marks] * [SparkBar](/docs/charts/sparkbar) — discrete magnitudes or win–loss * [DualSparkline](/docs/charts/dual-sparkline) — two series, one scale * [TrendArrow](/docs/charts/trend-arrow) — direction as a glyph * [Delta](/docs/charts/delta) — a single signed change * [Horizon](/docs/charts/horizon) — wide-range series in a slim band ## Next [#next] * [Sparkline API](/docs/charts/sparkline) * [Inline charts](/docs/inline-charts) * [When to use microcharts](/docs/when-to-use) * [Quickstart](/docs/quickstart) # Sizing & scaling (/docs/sizing) Every chart is a single `<svg>` with a `viewBox` and `preserveAspectRatio`, so scaling is a solved problem: give it a size in whatever way suits the layout and the geometry follows. There's no `ResizeObserver`, no layout effect, and no client JavaScript involved — a static chart scales purely through SVG and CSS. ## The three ways to size a chart [#the-three-ways-to-size-a-chart] | You want… | Do this | | ---------------------------- | -------------------------------------------------------- | | A sensible default | Pass nothing — every chart has an intrinsic box. | | An exact pixel size | Set `width` / `height` props (where the chart has them). | | To fill whatever contains it | Add `style={{ width: "100%", height: "auto" }}`. | > `width`/`height` are the common case, not a universal one. Grid charts derive their box from the cell instead — `ActivityGrid`, `CalendarStrip`, `GardenGrid` and `CohortTriangle` take `cell` and `gap`, `Honeycomb` takes `cell`, and `ConfusionGrid` takes `size`. The box then follows from the number of cells, so you tune the cell, not the frame. Glyph marks (`StatusDot`, `TrendArrow`, `MoonPhase`, `DicePips`, and friends) have one fixed intrinsic box and are sized with CSS. And `TokenConfidence` isn't an `<svg>` at all — it's text, so it inherits the font size of whatever it sits in. Everything below about `viewBox` scaling applies to the SVG charts. ## Default: data alone [#default-data-alone] `data` alone always renders something correct — at the chart's own intrinsic size. Each chart type ships a default box tuned to its shape: a Sparkline defaults to a wide, short 80 × 20, while a RubricStrip has no fixed default height at all — it grows a row per criterion. Good for dropping a mark into a table cell or a sentence without thinking about dimensions. ```tsx `" > <Sparkline data="[3, 5, 4, 8, 6, 9]" title="Weekly revenue" /> ``` ## Fixed size: width & height [#fixed-size-width--height] `width` and `height` are **viewBox units** — and because a static chart renders `<svg width={…} height={…}>`, they also set the rendered pixel box. So one pair of numbers controls both the coordinate space the geometry is drawn in and the size on screen. ```tsx `" > <Sparkline data="[3, 5, 4, 8, 6, 9]" width="200" height="48" title="Weekly revenue" /> ``` > Because `width`/`height` set the viewBox, they change how much room the geometry has — a taller RubricStrip gives each criterion a thicker row, a wider Sparkline spreads its points further apart. They are layout dimensions, not a zoom level. ## Fill the container [#fill-the-container] To make a chart fluid, stop pinning its pixel size and let CSS drive the width instead. The `viewBox` keeps the aspect ratio, so `height: auto` follows the width automatically. This is the one-liner for a KPI card, a responsive dashboard tile, or a full-width hero: ```tsx <Sparkline data={data} style={{ width: "100%", height: "auto" }} /> ``` The chart now grows and shrinks with its parent. Constrain it by sizing the container (or add a `max-width`), not the chart: ```tsx <div style={{ width: "100%", maxWidth: 320 }}> <Sparkline data={data} style={{ width: "100%", height: "auto" }} /> </div> ``` You can still pass `width`/`height` alongside fluid CSS — they become the chart's intrinsic aspect ratio and its size before CSS overrides the width. If you use a utility framework, the equivalent classes work just as well (`className="w-full h-auto"`). To give a whole row of charts one identical box rather than sizing each by hand, put `width`/`height` on `SparkGroup` instead: it enforces them on every series child that didn't set its own (and shares one scale while it's there — see [Formatting & scale](/docs/formatting#scale-the-domain-decision)). > `.mc-root` is `display: inline-block` by default (so a chart flows next to text). When you make one fill a block-level container, it behaves as expected — but if you ever see it not stretching, that's the reason: give it a `display: block` or a flex/grid parent. ## Interactive charts size the same way [#interactive-charts-size-the-same-way] Everything above applies **unchanged** to the `…/interactive` entries. An interactive chart wraps its SVG in a focusable `<span>` (it owns the pointer, keyboard, and touch gestures for the whole chart), but that wrapper and the SVG are always the **same box**: the wrapper is an `inline-block` that hugs its child, and the composed SVG inside is pinned to `width: 100%; height: auto`. Your `style` merges over the wrapper's base style and your `className` composes after its base class, so the same recipe fills it: ```tsx import { Sparkline } from "@microcharts/react/sparkline/interactive"; // identical to the static entry — fills its container <Sparkline data={data} style={{ width: "100%", height: "auto" }} />; ``` > Because the wrapper and the SVG share one box, hit-testing is exact at any size: the crosshair, highlight, and readout land under the cursor, a touch drag scrubs the unit actually beneath the finger, and a pinned selection stays on the right unit when the box reflows. An interactive chart is its static twin plus interaction, never a different size. ## Inline in a sentence [#inline-in-a-sentence] A word-sized chart in running prose should scale with the **font**, not a pixel box. Wrap it in `className="mc-inline"` (shipped in `styles.css`) and size it in `em` so it rides the text: ```tsx <p> Revenue is up this week{" "} <span className="mc-inline"> <Sparkline data={[3, 5, 4, 8, 6, 9]} style={{ height: "1em", width: "auto" }} /> </span>{" "} and holding. </p> ``` `mc-inline` handles vertical alignment; the `em` height ties the mark to the surrounding type size, so it stays proportional wherever the text lands. Alignment is a **baseline seat**, not a fixed nudge: the wrapper is an `inline-flex` box whose only child is the SVG, so it takes its baseline from the SVG's bottom edge and the mark stands on the text baseline exactly like a glyph. That's typeface-independent — bars sit where letters sit in any font. Symmetric glyph marks have no bottom edge to stand on, so `mc-inline` centers those on the cap band instead: `TrendArrow`, `StatusDot`, `MoonPhase`, `DicePips`, the radial dials and the other glyph shapes read like an icon set in running prose. You don't opt in. Which seat a mark gets isn't guessed from its class name — each chart reports its own plot box, measured in the same viewBox units it draws in, and the stylesheet seats the mark from that. So a chart whose padding changes can't drift out of alignment, and a chart that changes shape with its props carries the right seat for each: `SparkBar` stands on the baseline in bar mode and centers in win-loss, because only one of those has a real floor. Two tokens let you nudge the result if a particular typeface needs it — `--mc-inline-nudge` for every mark, and `--mc-glyph-nudge` for centered ones only. > Leave `<Delta>` bare — no `mc-inline` wrapper. It renders as inline text and already owns its own baseline. ## Strokes stay crisp at any scale [#strokes-stay-crisp-at-any-scale] Scaling an SVG normally thickens or thins its lines. microcharts sets `vector-effect: non-scaling-stroke` on data marks, so a line drawn at 200 px and the same line at 800 px keep the **same visual stroke weight** — the geometry scales, the ink doesn't. Rectilinear marks also use `shape-rendering: crispEdges` so bars and grids stay sharp. You get responsive sizing without the usual blurriness or weight drift. Stroke weight is a token, not a size artifact — set `--mc-stroke-width` (see [Theming](/docs/theming)) if you want it heavier or lighter, independent of how big the chart is. For a whole dense context — a table packed with sparklines — reach for `--mc-density`: one scalar that scales stroke weight, label size, and small-multiple gap together (`< 1` tighter, `> 1` airier). It tunes the ink and type, never the box, so `width`/`height` still own the geometry. # Theming (/docs/theming) microcharts theming is CSS custom properties, all the way down. There's no theme provider you *have* to wire up and no Tailwind requirement — set a `--mc-*` variable at any scope and every chart inside it retunes, with zero re-render and no build step. (Prefer a React component to a raw attribute? [`MicroProvider`](#a-component-api-if-you-prefer) wraps the same contract.) Two ideas carry the whole system: **a token** is one variable you set, and **a scope** is where you set it. Learn those two and the rest of this page is just the vocabulary — every colour, weight, and timing you can reach for, and a studio that hands you any combination as ready-to-paste CSS. ## Override a token [#override-a-token] ```css .brand { --mc-accent: #7c3aed; --mc-stroke-width: 2; } ``` Every chart inside `.brand` now draws with that accent and stroke weight. Precedence is predictable: a **prop** wins over a **CSS-variable scope**, which wins over a **preset**, which wins over the built-in default. ```tsx <Sparkline data={data} color="#7c3aed" /> <Sparkline data={data} color="var(--mc-positive)" />`" > <Sparkline data="[3, 5, 4, 8, 6, 9]" width="110" height="30" title="Default" /> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="110" height="30" color="#7c3aed" title="Custom" /> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="110" height="30" color="var(--mc-positive)" title="Token" /> ``` ## Scope it anywhere [#scope-it-anywhere] Because the tokens cascade, the scope is yours to choose — the whole app, one brand section, a single card, or one chart. Set a token high and every chart below inherits it; override it lower and only that subtree changes. ```tsx // app-wide, once <html style={{ "--mc-accent": "var(--brand-500)" }}> // just this card's charts <div style={{ "--mc-stroke-width": 2, "--mc-gap": "0.15em" }}> <SparkBar data={weekly} /> </div> ``` Bind `--mc-accent` to your existing brand variable and the charts follow your design system automatically — no per-chart props, no duplicated color values. ## The token set [#the-token-set] That's the whole mechanism. What's left is the vocabulary: about two dozen custom properties cover the entire surface, and setting any of them at any scope retunes every chart inside. Here are the colour tokens with their built-in light and dark values — every chip is the real shipped default, click to copy the hex: <TokenSwatches /> Below is the same set as raw CSS — the colours plus the geometry, motion, and readout-surface tokens — ready to paste and override. (Want a specific style or accent instead of the bare defaults? The [studio](#copy-tokens) a little further down builds any combination for you.) ```css :root { /* Semantic colour */ /* Default ink: lines, bars, labels. Dark mode is hand-tuned, not inverted. */ --mc-stroke: #1a1917; /* Good direction — colour-blind-safe viridian; pair with ▲. */ --mc-positive: #0e7a5f; /* Bad direction — colour-blind-safe terracotta; pair with ▼. */ --mc-negative: #bd4b2d; /* No-signal marks: baselines, inactive points, empty cells. */ --mc-neutral: #8a8986; /* Emphasis colour — rebind to your brand. */ --mc-accent: #1f6091; /* Normal-range shading, derived from the ink. */ --mc-band: color-mix(in oklab, var(--mc-stroke) 8%, transparent); /* MoonPhase lit area — warm amber; mono/print/eink retune it with the ink. */ --mc-moon: #c1922f; /* Categorical palette — matte jewel tones; multi-series only, lightness-ordered. Each has a hand-tuned brighter twin on dark surfaces (same hue, lifted). */ --mc-cat-1: #d2982f; --mc-cat-2: #5b9fd4; --mc-cat-3: #2e8c66; --mc-cat-4: #285788; --mc-cat-5: #c2543a; --mc-cat-6: #a85c8c; /* Geometry */ /* Light by default for inline use; bump to ~2 when standalone. */ --mc-stroke-width: 1.5; /* Spacing between grouped marks; em-based so it scales with the font. */ --mc-gap: 0.25em; /* Uniform density scale — compact (<1) vs comfortable (>1). Tunes stroke weight, label size, and small-multiple gap together; the box set by width/height is untouched. */ --mc-density: 1; /* Direct-label text size, relative to the chart's font. */ --mc-label-size: 0.75em; /* Direct-label weight. */ --mc-label-weight: 400; /* `.mc-inline` seats marks on the text baseline (font-independent). This is an optional extra optical shift on top — 0 by default; set it only if a particular face wants marks a hair off the line. */ --mc-inline-nudge: 0em; /* Extra optical shift for centred marks (arrow, dot, moon, dials, strips) on top of the cap-band seat — font-relative, negative lifts. 0em by default: the seat already lands on the true cap midpoint, so there is nothing left to correct unless a display face has an unusual cap ratio. */ --mc-glyph-nudge: 0em; /* Motion & type */ /* Motion duration — readout transitions, value pulses, entrance animation. */ --mc-duration: 300ms; /* Ease-out entrance; no bounce or loop. */ --mc-easing: cubic-bezier(0.22, 1, 0.36, 1); /* Inherits the host UI font + tabular numerals by default. */ --mc-font: inherit; /* Face for figures + labels — tracks --mc-font; point at a brand or mono face to give numbers their own typeface without touching the page font. */ --mc-font-numeric: var(--mc-font); /* Interactive readout chip (hover, focus, or a pinned selection). Defaults to system canvas. */ --mc-surface: Canvas; --mc-surface-ink: CanvasText; --mc-surface-edge: color-mix(in oklab, CanvasText 16%, transparent); } ``` ## Semantic vs categorical color [#semantic-vs-categorical-color] The colour tokens split into two groups, and knowing which is which is what keeps a theme honest. **Semantic tokens keep their meaning.** Swapping `--mc-accent` retints the one emphasis color, but `--mc-positive`/`--mc-negative` still mean up and down — so a preset can restyle a chart without ever changing what it says. Color encodes; it never merely decorates. **Categorical colors are a last resort.** Most microcharts show one series and never touch the palette. When a chart genuinely needs several, the six `--mc-cat-*` hues are lightness-ordered for grayscale and colour-vision separation, and gold leads because true yellow is too low-contrast on a light surface. To recolour the series on *one* instance without touching the global palette, the categorical charts (`SegmentedBar`, `StackedArea`, `PartitionStrip`, `Hypnogram`, `MicroDonut`) take a `colors` array — cycled per series, overriding `--mc-cat-*` just there. A rolled-up "Other" segment stays neutral rather than taking a series colour. ```tsx `"> <SegmentedBar data="[ { label: "A", value: 34 }, { label: "B", value: 26 }, { label: "C", value: 22 }, { label: "D", value: 18 }, ]" colors="["#2563eb", "#db2777", "#65a30d", "#f59e0b"]" width="220" height="16" title="Custom series colours" /> ``` ## Presets [#presets] Setting tokens by hand is one path; a **preset** is a whole look bundled under one name, applied with a `data-mc-theme` attribute — pure CSS, zero JavaScript. They change how charts *look*, never what the data *means*. `modern` is what you get with no attribute at all: it's the base token set, not a bundle layered on top, so there's nothing to apply. ```tsx <Sparkline data={data} dots="minmax" /></div> {/* modern — the default, no attribute */} <div data-mc-theme="editorial"><Sparkline data={data} dots="minmax" /></div> <div data-mc-theme="vivid"><Sparkline data={data} dots="minmax" /></div> <div data-mc-theme="mono"><Sparkline data={data} dots="minmax" /></div>`" > <div> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="100" height="28" dots="minmax" title="modern" /> </div> <div data-mc-theme="editorial"> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="100" height="28" dots="minmax" title="editorial" /> </div> <div data-mc-theme="vivid"> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="100" height="28" dots="minmax" title="vivid" /> </div> <div data-mc-theme="mono"> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="100" height="28" dots="minmax" title="mono" /> </div> ``` What each preset retunes — every other token stays at its default: <PresetDeltas /> The last two — `print` and `eink` — are output-context bundles rather than a look you'd ship on screen. `print` pins a near-black ink, deepens the valence colours for CMYK, and thins the stroke to `1.25`; `eink` drops to grayscale and lets sign ride lightness (positive black, negative gray) with a `2` stroke for a low-refresh e-paper panel. Apply them the same way — `data-mc-theme="print"` on the region you're about to render. Both pin a fixed light-surface ink, so both also ship hand-tuned dark twins: on a dark viewer `eink` flips to true night mode (white ink on black) and `print` lifts to a dark-paper ink, while the stroke weight and band identity carry over. The look presets — `editorial`, `mono`, `vivid`, `print`, `eink` — also answer to `data-mc-preset`, the page-global form: set it once on `<html>` for an app shell, and a nearer `data-mc-theme` still wins by proximity. `dark` is the exception, matching `data-mc-theme="dark"` only, because it's a colour-scheme scope rather than a look you'd pin app-wide. > Every preset above carries a **Copy tokens** button, and the [studio below](#copy-tokens) lets you pair any preset with your own accent and copy the result for both modes. This site's appearance menu (the palette icon in the nav) applies the same bundles live across every page — and picking an accent there re-hues every chart on the site, including the categorical palette, because it derives one with [`defineTheme`](#build-a-theme-from-one-colour) exactly like the studio does. It's the exact token contract you'd use in your own app. ## Copy the tokens [#copy-tokens] Everything above, in one place — the live studio. Pick a style, add your brand accent, choose a mode, and copy the exact `--mc-*` block, light and hand-tuned dark together, ready to paste into your app. The preview renders real charts in both modes and names each role it paints, so a choice shows up the instant you make it: the emphasis line takes your accent *and* the categorical bars re-hue to a matched palette **derived from it** by [`defineTheme`](#build-a-theme-from-one-colour) — the same engine the nav's appearance menu uses to re-theme the whole site. What you preview is exactly what you copy, and exactly what the library ships — never an approximation. <TokenStudio /> Paste the CSS into any stylesheet and every chart in scope retunes. Prefer the component API? Switch the format to a tokens object and spread it onto [`MicroProvider`](#a-component-api-if-you-prefer) — or reach for [`defineTheme`](#build-a-theme-from-one-colour) directly to derive that matched palette in code. ## A component API, if you prefer [#a-component-api-if-you-prefer] Everything above works through plain attributes and CSS variables — but if you'd rather set the theme in JSX, `MicroProvider` wraps the same contract in a component. It's hook-free and RSC-safe, so it works in Server Components too. ```tsx import { MicroProvider } from "@microcharts/react"; <MicroProvider theme="editorial" tokens={{ "--mc-accent": "var(--brand-500)" }}> <Sparkline data={data} /> </MicroProvider>; ``` It renders a single `<div>` that sets `data-mc-theme` (the preset) plus any `tokens` as inline `--mc-*` custom properties — identical to writing them by hand. `theme="modern"` writes no attribute, since modern *is* the base token set. `theme` takes any preset (`modern`, `editorial`, `mono`, `vivid`, `dark`, plus the output-context `print` and `eink`); `tokens` takes any `--mc-*` overrides. Reach for whichever reads better in your code — it's the same cascade underneath. ## Build a theme from one colour [#build-a-theme-from-one-colour] Setting a token or two by hand is the common case. For a whole brand theme — a matched categorical palette *and* hand-tuned dark twins for every colour — reach for `defineTheme` from `@microcharts/react/theme`. Hand it your brand accent and it derives the rest in OKLCH: a harmonized, colour-blind-safe categorical palette and a lifted dark-mode twin for each token. It never nudges the positive/negative hues off their CVD-safe green/vermillion split, so a derived theme stays as honest as the defaults. ```tsx import { defineTheme } from "@microcharts/react/theme"; import { MicroProvider } from "@microcharts/react"; const brand = defineTheme({ accent: "#6d28d9" }); // spread the tokens onto one scope… <MicroProvider style={brand.style}> <SegmentedBar data={mix} /> </MicroProvider>; // …or emit a global stylesheet — includes a prefers-color-scheme: dark block const css = brand.css(":root"); ``` One accent, a full derived palette (these are the real values `defineTheme` returns): ```tsx <SegmentedBar data={mix} title="Derived palette" /> </MicroProvider>`" > <div style="{ "--mc-accent": "#6d28d9", "--mc-cat-1": "#8b7cc5", "--mc-cat-2": "#9a4f72", "--mc-cat-3": "#bc7548", "--mc-cat-4": "#6d7218", "--mc-cat-5": "#2d9e82", "--mc-cat-6": "#04759f", }" > <SegmentedBar data="[ { label: "A", value: 34 }, { label: "B", value: 26 }, { label: "C", value: 18 }, { label: "D", value: 12 }, { label: "E", value: 10 }, ]" width="220" height="16" title="Derived palette" /> </div> ``` The result carries everything you need for any delivery: `vars` (a `--mc-*` object), `darkVars` (the derived dark twins, empty when `dark: false`), `style` (an alias of `vars`, ready to spread onto `MicroProvider` or any element), `css(selector = ":root")` (a string with the `prefers-color-scheme: dark` block included), `toString()` (the same as `css(":root")`), and `extend()` to spin a variant off an existing theme. Extend a preset, pin any token, or pass an explicit palette when you don't want derivation: ```tsx // extend a preset — the brand accent flows through defineTheme({ extends: "editorial", accent: "var(--brand-500)", }); // bring your own categorical palette (no derivation) defineTheme({ accent: "#6d28d9", cat: ["#2563eb", "#db2777", "#65a30d"], }); // derive a specific number of categorical tones instead of the default six defineTheme({ accent: "#6d28d9", cat: 3 }); // opt out of accent-seeded derivation, or out of dark twins entirely defineTheme({ accent: "#6d28d9", derive: false }); defineTheme({ accent: "#6d28d9", dark: false }); // override just some dark twins (the rest stay auto-derived) defineTheme({ accent: "#6d28d9", dark: { accent: "#a78bfa" } }); // compose a compact variant off an existing theme defineTheme({ density: 0.85 }).extend({ labelWeight: 500 }); // pin geometry directly — strokeWidth, gap, labelSize, labelWeight, density defineTheme({ accent: "#6d28d9", strokeWidth: 2 }); ``` It's pure, dependency-free, and tree-shaken out of any bundle that never imports it. ## Density [#density] `--mc-density` is a single scalar that scales stroke weight, label size, and small-multiple gap together — one knob for compact tables (`< 1`) or an airier standalone layout (`> 1`). It tunes the ink and type, not the box: the plot size still comes from `width`/`height`, so nothing reflows unexpectedly. ```css /* a denser table of sparklines */ .metrics-table { --mc-density: 0.85; } ``` One asymmetry worth knowing: **stroke and gap scale without limit, but the label stops scaling at 1.25.** Direct labels sit in a gutter the chart reserves from a character-count estimate while it draws — server-side, where text cannot be measured. That reservation is fixed at render time and cannot see a CSS variable set later, so past about 1.25 the text outgrows the space held for it and paints outside the chart. Below `1` there is no such limit: the label shrinks inside a gutter already reserved for something bigger, which is always safe. So `--mc-density: 2` gives you double-weight strokes and double gaps, with labels at 1.25×. If you want genuinely larger text, scale the chart — `width`/`height`, or `--mc-label-size` — rather than leaning on density. ## The font [#the-font] `--mc-font` defaults to `inherit`, so charts adopt the font of whatever contains them and read as part of your interface. That means the rule is really about your page, not the library: if the surrounding page sets a `font-family`, charts follow it for free. If it doesn't — as in some minimal starters and code sandboxes — SVG text falls back to the browser default (usually a serif), and labels come out looking wrong. Two fixes, either works: give your page a font the normal way, or font the charts directly by pointing `--mc-font` at a stack. ```css :root { /* charts only — the rest of the page is untouched */ --mc-font: system-ui, sans-serif; } ``` Numbers always render with `tabular-nums` regardless, so columns of figures stay aligned in any font. Want the figures in a dedicated face — a tabular numeric font, or a mono for a data-dense KPI — without changing the label font? Point `--mc-font-numeric` at it; it defaults to `--mc-font`, so leaving it alone keeps everything on one typeface. `--mc-label-weight` (default `400`) does the same for label weight. ```css :root { --mc-font: Inter, sans-serif; /* labels */ --mc-font-numeric: "IBM Plex Mono", monospace; /* figures */ } ``` ## The readout surface [#the-readout-surface] The only opaque plane in the whole library is the value chip an interactive chart shows for its active unit — under the pointer, under keyboard focus, or pinned in place after a click, tap, or **Enter**. Its three `--mc-surface*` tokens default to the system `Canvas`, so it adapts to light, dark, and forced-colors with no configuration. Point them at your popover tokens when you want the chip to match a themed surface exactly — one set of tokens covers the hovered, focused, and pinned states alike. ## Dark mode and forced colors [#dark-mode-and-forced-colors] Dark values are hand-tuned per token — never auto-inverted, so overriding one light value can't quietly break the dark surface. microcharts follows `prefers-color-scheme` out of the box, and you can force a scope with `data-mc-theme="dark"`. Charts never paint their own background, so they always sit cleanly on your surface. If your app toggles theme with a **class** (next-themes `.dark`, a `[data-theme]` attribute, …) rather than the OS media query, rebind the tokens under that class the same way you bind accent — the library's media-query defaults are `:where()` zero-specificity, so your class rules win: ```css :root { --mc-accent: var(--brand); } .dark { --mc-stroke: #eae9e6; --mc-positive: #45a385; --mc-negative: #df7856; --mc-accent: var(--brand); /* …or data-mc-theme="dark" on a scope, if you prefer the shipped dark bundle */ } ``` ### Frosted or translucent surfaces [#frosted-or-translucent-surfaces] Default valence inks clear 4.5:1 on opaque white and near-black. On a frosted glass / tinted panel the composited backdrop is quieter, so deepen `--mc-stroke` / `--mc-positive` / `--mc-negative` / `--mc-neutral` on that surface until contrast holds — don't patch chart CSS. (This docs site does exactly that under `:root` / `.dark` so marks stay legible on glass.) Under Windows High Contrast (`forced-colors`), the semantic tokens defer to system colors — ink to `CanvasText`, accent to `Highlight`, muted marks to `GrayText` — so a chart stays legible even when your palette is overridden entirely. `prefers-contrast: more` is handled too: charts bump `--mc-stroke-width` to `2` and deepen `--mc-band` from an 8% to a 16% mix of the ink, so lines and normal-range shading both gain weight without you configuring anything. # Troubleshooting (/docs/troubleshooting) Most issues trace back to one of a handful of causes. This page is the fast path to each fix; the full explanation for each one lives on its own guide page, linked below. ## Charts render with no color, no strokes, just plain shapes [#charts-render-with-no-color-no-strokes-just-plain-shapes] The stylesheet isn't loaded. Every visual property — color, stroke weight, label size, the whole theme — comes from `styles.css`, imported once: ```tsx import "@microcharts/react/styles.css"; ``` Without it, a chart is still valid, accessible SVG (the markup and the accessible name are both there), it just has no styling applied — geometry with no ink. See [Quickstart](/docs/quickstart#compatibility) for where to put the import in your framework. ## A chart is invisible (or nearly) on a colored or dark panel [#a-chart-is-invisible-or-nearly-on-a-colored-or-dark-panel] Charts never paint their own background — they're transparent SVG, always. On a plain light or dark page this is invisible because the built-in light/dark tokens track `prefers-color-scheme`. It breaks when a chart sits on a surface whose color doesn't match the *page's* color scheme — a dark-branded card on an otherwise light page, or a colored KPI tile — because the tokens don't know that scope looks dark; they only know what the OS/browser reports. Fix it by rebinding the token scope to match the surface, not the page: ```css .dark-panel { --mc-stroke: #f5f5f5; /* text + data strokes; add --mc-neutral for muted labels */ } ``` or force the whole preset for that scope: ```tsx <div data-mc-theme="dark"> <Sparkline data={data} /> </div> ``` See [Theming](/docs/theming) for the full token set and how scope, preset, and prop precedence works. ## `Error: ... 'use client' ...` when importing a chart [#error--use-client--when-importing-a-chart] You imported a chart's `/interactive` entry into a Server Component: ```tsx // ❌ interactive entries are client components — this throws in an RSC import { Sparkline } from "@microcharts/react/sparkline/interactive"; ``` Two ways out: render the static default entry instead if you don't actually need hover, keyboard, touch, or selection — ```tsx import { Sparkline } from "@microcharts/react/sparkline"; ``` — or, if you do need interactivity, move the import into a component marked `"use client"` and render that component from your server tree. See [Quickstart](/docs/quickstart#add-interactivity) for the static-vs-interactive split. ## `onPointFocus` / `onRunFocus` no longer fire [#onpointfocus--onrunfocus-no-longer-fire] They were removed when every interactive chart moved onto one shared contract. The replacement is `onActive`, which fires for the same reason on every chart in the catalog rather than under a different name per chart: ```tsx // ❌ removed <Sparkline data={data} onPointFocus={(i) => setHovered(i)} /> // ✅ one name, everywhere <Sparkline data={data} onActive={(d) => setHovered(d?.index ?? null)} /> ``` The payload is a `MicroDatum` — `{ index, value, label?, formatted? }` (`value` is the raw number, `formatted` the chart's ready-to-display string) — or `null` when the chart clears. `onPointFocus` on Sparkline and SparkBar and StreakSpark's `onRunFocus` map across directly. Note that `index` identifies the chart's *navigable unit*, which isn't always a series index: on Waveform it's a bucket, on Hypnogram a run, on SegmentedBar a segment. Each chart's page names its own unit. If you also want click-to-pin, add `onSelect` — see [Accessibility](/docs/accessibility#one-interaction-contract). ## `animate` does nothing [#animate-does-nothing] The entrance engine isn't loaded. `animate` is a flag; the code that runs the animation ships in a separate side-effect import you add once, anywhere in your client bundle: ```tsx import "@microcharts/react/motion"; ``` In development the chart logs exactly this to the console when the engine is missing. Three other reasons `animate` is correctly inert, none of them bugs: the reader has `prefers-reduced-motion: reduce`, the chart is a static entry (`animate` is an `/interactive`-only prop), or the markup came from the server and is being hydrated rather than freshly mounted — an entrance would mean animating content the reader can already see. The entrance also runs once per mount by design; remount with a changed `key` to replay it. ## The chart won't stretch to fill its container [#the-chart-wont-stretch-to-fill-its-container] `.mc-root` — the chart's own `<svg>` — is `display: inline-block` by default, so it flows next to text instead of stretching. Give it fluid sizing explicitly: ```tsx <Sparkline data={data} style={{ width: "100%", height: "auto" }} /> ``` and make sure the *parent* is block-level (a flex or grid item, or a `div`) — a chart can't grow past an inline parent no matter what you set on the chart itself. This is identical for `…/interactive` entries: `style`, `className`, and `width`/`height` size an interactive chart exactly the way they size its static twin, and hit-testing stays exact at any size — the crosshair tracks the cursor and a touch drag scrubs the unit under the finger. Full recipes, including the inline-in-a-sentence case, are on [Sizing & scaling](/docs/sizing). ## A chart stacks on its own line instead of sitting inline with text [#a-chart-stacks-on-its-own-line-instead-of-sitting-inline-with-text] This is usually a CSS reset, not a microcharts bug. `.mc-root`'s `display: inline-block` is declared inside a zero-specificity `:where()` so your styles always win — including ones you didn't mean to apply. Tailwind's Preflight sets a plain `svg { display: block; ... }` rule, which has *higher* specificity than any `:where()` selector and so overrides it, dropping the chart onto its own block-level line. Re-assert the layout you want at the call site: ```tsx <Sparkline data={data} className="inline-block" /> ``` or wrap it in `className="mc-inline"` for text-flow placement — see [Sizing & scaling](/docs/sizing#inline-in-a-sentence). ## Chart labels look wrong — a serif fallback, or mismatched with the page [#chart-labels-look-wrong--a-serif-fallback-or-mismatched-with-the-page] Charts inherit `font-family` from the page; they don't set one of their own. If the surrounding page never declares a font (a bare sandbox, a minimal starter), SVG text falls back to the browser's default serif. See [Theming → The font](/docs/theming#the-font) for why it inherits and how to set it per-scope. # microcharts vs Chart.js for inline charts (/docs/vs-chartjs) [Chart.js](https://www.chartjs.org) is a Canvas-first chart library with a large plugin ecosystem, usually wrapped by [`react-chartjs-2`](https://react-chartjs-2.js.org) in React apps. microcharts is not a replacement for it — a dense analyst dashboard or a report full of chart panels is Chart.js territory. This page compares the two for one narrow job: a chart the size of a word, inside a sentence, a table cell, or a KPI card. The broader positioning lives in [When to use microcharts](/docs/when-to-use) and [Full chart libraries](/docs/full-chart-libraries). ## The numbers [#the-numbers] <VsChartJsTable /> microcharts numbers come from `.size-limit.json` — the CI gate, re-measured on every build. The Chart.js figures are pinned with version and date; they are orientation, not a scoreboard. ## Where the difference actually shows [#where-the-difference-actually-shows] **Renderer.** Chart.js draws to a `<canvas>`, and a canvas only exists in the browser — there is no static-HTML output path. The chart appears after JavaScript runs. microcharts renders SVG markup, so the mark is real DOM: it exists in the server-rendered HTML, prints correctly, and scales crisply at any zoom. **Server Components.** `react-chartjs-2` manages the canvas with hooks and effects, so it runs in a client boundary and ships Chart.js to the browser. The microcharts default export is hook-free static SVG — an RSC can render it with zero client JavaScript. **Accessibility.** A canvas is a bitmap to assistive technology; the Chart.js docs recommend supplying your own fallback content or ARIA labeling per chart, and plugins exist to help. That path works — it is just manual. Every microchart defaults to `role="img"` plus a natural-language summary generated from the data. **Text and theming.** Inline marks sit next to your text, so they must inherit its rhythm. SVG takes CSS custom properties, `currentColor`, and container-relative sizing directly; a canvas repaints through JavaScript when the theme flips. ## Reach for Chart.js [#reach-for-chartjs] * Dashboard or report canvases with many series and heavy point counts * You already run Chart.js configs or depend on its plugin ecosystem * Canvas rendering is a requirement, not an implementation detail ## Reach for microcharts [#reach-for-microcharts] * The mark lives inline — prose, cells, tabs, KPI cards, streamed AI replies * You want the chart present in server-rendered HTML, with zero client JS by default * You want an accessible name without per-chart wiring * Per-mark budget: <SizeMarketing /> gzip, zero runtime dependencies ## What this page is not saying [#what-this-page-is-not-saying] * Not "Canvas is wrong" — above a few thousand points it is usually right * Not "Chart.js cannot be made accessible" — it can; it is manual * The gzip figures are dated pins, not live measurements ## Next [#next] * [Full chart libraries](/docs/full-chart-libraries) — Recharts and Chart.js in one view * [microcharts vs Recharts](/docs/vs-recharts) * [When to use microcharts](/docs/when-to-use) * [Accessibility](/docs/accessibility) — what the defaults actually do # microcharts vs MUI X Sparkline — bundle size and RSC comparison (/docs/vs-mui-x-sparkline) [MUI X Charts](https://mui.com/x/react-charts/) ships `SparkLineChart` — an inline-sized chart from the same family as its full Line, Bar, and Pie charts, themed by and integrated with Material UI. If your product is built on MUI and the sparkline sits in a MUI dashboard, that integration is a real advantage and this page may talk you out of nothing. The comparison matters when the mark must be cheap, static, or independent of MUI: a table column of trends, a KPI row in an RSC, a chart in a streamed AI reply. ## The numbers [#the-numbers] <VsMuiXTable /> The two MUI scenarios are deliberate: inside a MUI app the Material core is already in your bundle, so the sparkline's marginal cost is the smaller figure. Without MUI, `@mui/material` and `@mui/system` are required peer dependencies — you install and ship them to render one sparkline. ## Where the difference actually shows [#where-the-difference-actually-shows] **Bundle cost.** `SparkLineChart` shares MUI X's charting core (data providers, interaction plugins, vendored d3). That architecture is what makes the full chart family consistent — and it is why one sparkline carries tens of kilobytes. microcharts charges per chart subpath: <ChartSize slug="sparkline" /> for Sparkline, catalog band <SizeMarketing /> gzip. **Server Components.** `SparkLineChart` is marked `'use client'` — the server can emit initial HTML, but the component always hydrates and ships its JavaScript. The microcharts default export is hook-free static SVG with zero client JS; interactivity is a separate `/interactive` import. **Accessibility defaults.** As published, the `SparkLineChart` SVG renders with `aria-hidden="true"` and no accessible name — the chart is invisible to assistive technology unless you label it yourself. Every microchart defaults to `role="img"` with a natural-language summary generated from the data. **Theming.** MUI X charts theme through the MUI theme object — coherent if you live there. microcharts themes through `--mc-*` CSS custom properties at near-zero specificity, so it follows any design system, including a MUI one. ## Reach for MUI X Sparkline [#reach-for-mui-x-sparkline] * Your app is already on MUI and the chart sits among MUI components * You want one vendor for the sparkline and the full charts beside it * You use MUI X's tooltip, highlighting, and animation stack elsewhere ## Reach for microcharts [#reach-for-microcharts] * The mark must not pull MUI (or anything) into the bundle — zero runtime dependencies * You render from RSCs and want zero client JavaScript for static marks * Accessibility should be the default, not a labeling task per chart * You need chart types beyond sparklines at word size — <CatalogTotal /> types, one grammar ## What this page is not saying [#what-this-page-is-not-saying] * Not "MUI X is bloated" — the shared core is the price of a consistent full-chart family * Not "never use SparkLineChart" — inside a MUI dashboard it is the coherent choice * MUI X Charts (community) is MIT and actively maintained; the sizes are dated pins from the published package ## Next [#next] * [When to use microcharts](/docs/when-to-use) * [microcharts vs Recharts](/docs/vs-recharts) * [React sparklines](/docs/react-sparklines) * [Theming](/docs/theming) — fitting charts into an existing design system # microcharts vs react-sparklines — React sparkline comparison (/docs/vs-react-sparklines) [`react-sparklines`](https://www.npmjs.com/package/react-sparklines) put sparklines into thousands of React apps and still gets massive weekly downloads. It is the package many "react sparkline" searches land on, so if you are choosing between it and microcharts, this page is the factual side-by-side. It is not a takedown — the package earned its adoption. ## The numbers [#the-numbers] <VsReactSparklinesTable /> ## Where the difference actually shows [#where-the-difference-actually-shows] **Maintenance.** `react-sparklines` last published in 2017 (`1.7.0`). It predates hooks and Server Components — nothing from that era can be expected to target them. microcharts is actively maintained against React 18 and 19, with StrictMode-safe rendering tested in CI. **Accessibility.** `react-sparklines` renders a bare `<svg>` — no `role`, no `<title>`, no accessible name; a screen reader finds nothing. Every microchart is `role="img"` with a natural-language summary generated from the data (`describeSeries`), and interactive entries add keyboard navigation with a polite live region. **Server Components.** `react-sparklines` components are class components, which need a client boundary in an App Router app. The microcharts default export is hook-free static SVG that renders directly in an RSC with zero client JavaScript. **Scope.** microcharts is a word-sized catalog — <CatalogTotal /> chart types, one grammar: `data` alone renders something correct, and the same prop names mean the same thing on every chart. Sparkline is one entry in it. `react-sparklines` is one visual idea with composable overlays. **Size.** Both are small. `react-sparklines` is a single \~7.9 kB gzip package; microcharts charges per chart subpath (<ChartSize slug="sparkline" /> for Sparkline) with a CI gate that keeps every chart inside its budget. ## When react-sparklines is still fine [#when-react-sparklines-is-still-fine] * A legacy codebase already uses it, the charts are decorative, and nothing is broken * You need its exact composable-overlay API and have your own accessibility layer No urgency to migrate in those cases. The gaps above matter when accessibility, RSC, or maintenance actually bite. ## Migrating [#migrating] The shapes map directly: ```tsx // react-sparklines import { Sparklines, SparklinesLine } from "react-sparklines"; <Sparklines data={[3, 5, 4, 8, 6, 9]} width={100} height={20}> <SparklinesLine color="steelblue" /> </Sparklines>; // microcharts import { Sparkline } from "@microcharts/react/sparkline"; <Sparkline data={[3, 5, 4, 8, 6, 9]} width={100} height={20} color="steelblue" title="Weekly revenue" />; ``` `title` gives the chart its accessible subject; the summary is generated from the data. Bars map to [SparkBar](/docs/charts/sparkbar), reference lines to [`<Threshold>`](/docs/annotations). ## Next [#next] * [React sparklines](/docs/react-sparklines) — the mark itself, in depth * [Sparkline API](/docs/charts/sparkline) * [When to use microcharts](/docs/when-to-use) * [Accessibility](/docs/accessibility) # microcharts vs Recharts — inline charts comparison (/docs/vs-recharts) [Recharts](https://recharts.org) is a full chart library and microcharts is not a replacement for it. If your page *is* the chart — axes, legend, tooltip, brush — stop reading and use Recharts. This page compares the two for exactly one job: a word-sized chart *inside* an interface, where the surface is mostly words and UI. The broader positioning lives in [When to use microcharts](/docs/when-to-use) and [Full chart libraries](/docs/full-chart-libraries). This page is the measured detail for the Recharts decision. ## The numbers [#the-numbers] <VsRechartsTable /> Both microcharts columns come from `.size-limit.json`, the CI gate that fails the build when a chart grows past its budget. The Recharts numbers are pinned with version, method, and date — they are orientation, not a scoreboard, and they will age. ## Where the difference actually shows [#where-the-difference-actually-shows] **Bundle cost per mark.** A tree-shaken Recharts `LineChart` carries the shared Recharts core. That cost is fine amortized over a dashboard; it is hard to justify for one sparkline in a table header. microcharts imports one chart per subpath, so a page that uses only `Sparkline` pays only for `Sparkline`. **Server Components.** Recharts components are hook-based, so in an App Router app they run inside a client boundary and ship their JavaScript. The microcharts default export is hook-free static SVG — it renders in an RSC with zero client JavaScript, and interactivity is a separate opt-in `/interactive` import. **Accessibility defaults.** Recharts ships an accessibility layer, on by default in v3 — keyboard navigation and ARIA roles on the chart surface. A natural-language description of the data is still yours to write. Every microchart is `role="img"` with that description generated from the data by default (`describeSeries`); the decorative opt-out is explicit (`summary={false}`). **Chart chrome.** Recharts draws axes, ticks, legends, and tooltips because dashboard surfaces need them. microcharts hard-codes them away because word-sized marks cannot afford them. Neither choice is a defect; they serve different surfaces. ## Reach for Recharts [#reach-for-recharts] * The page is mostly chart: analytics views, report panels, explorable dashboards * You need ticks, legends, brush, zoom, or a tooltip that follows the pointer * Your team already has a Recharts component tree it trusts ## Reach for microcharts [#reach-for-microcharts] * The mark sits in a sentence, a table cell, a tab, a KPI card, or a streamed AI reply * You want static chart SVG out of a React Server Component with nothing to hydrate * You want an accessible name generated from the data without wiring it per chart * Budget matters per mark: <SizeMarketing /> gzip, zero runtime dependencies ## Same app, both libraries [#same-app-both-libraries] This is the common ending, not a compromise: ```tsx // analytics page — Recharts <ResponsiveContainer width="100%" height={240}> <LineChart data={rows}>…</LineChart> </ResponsiveContainer>; // the table that links to it — microcharts import { Sparkline } from "@microcharts/react/sparkline"; <Sparkline data={row.series} width={72} height={16} dots="none" summary={false} />; ``` ## What this page is not saying [#what-this-page-is-not-saying] * Not "Recharts is heavy" — it is correctly sized for the job it does * Not "microcharts can replace your dashboards" — it cannot and does not try * The gzip figures are dated pins, not live measurements ## Next [#next] * [Full chart libraries](/docs/full-chart-libraries) — Recharts and Chart.js in one view * [When to use microcharts](/docs/when-to-use) — the product decision * [microcharts vs Chart.js](/docs/vs-chartjs) * [Performance](/docs/performance) — our own CI receipts # microcharts vs visx — tiny charts comparison (/docs/vs-visx) [visx](https://airbnb.io/visx/) is Airbnb's collection of low-level visualization primitives: shapes, scales, axes, and gradients you compose into your own charts. It is deliberately not a chart library — you are the chart library. microcharts is the opposite bet: finished, opinionated word-sized marks with the design decisions already made. That makes this less a competition than a fork in the road. Both keep bundles lean through per-package (visx) or per-chart (microcharts) imports; the real question is who does the chart design — you or the library. ## The numbers [#the-numbers] <VsVisxTable /> The visx figure is a floor, not a typical cost: `LinePath` plus one scale, before curves, tooltips, or axes. Each `@visx/*` package you add brings its own dependencies (d3 arrives vendored through `@visx/vendor`). ## Where the difference actually shows [#where-the-difference-actually-shows] **Who owns the design.** With visx you decide geometry, padding, label placement, empty-data behavior, negative-value handling, and color semantics per chart — full control, and a real design task at 16 pixels tall. microcharts hard-codes those decisions: areas anchor at zero, direction is never color-alone, labels reserve deterministic gutters, empty and all-null data render documented placeholders. **Who owns accessibility.** A visx `LinePath` renders a bare `<path>` — `role`, `<title>`, and a description of the data are yours to author on every chart you build. Every microchart defaults to `role="img"` with a natural-language summary generated from the data. **Dependency posture.** visx keeps React in control of the DOM and slices d3 into per-package imports — genuinely lighter than shipping all of d3. microcharts goes further for its narrower job: scales, paths, easing, color, and summaries are in-house, so `dependencies: {}` is a CI-enforced invariant. **Edge cases.** NaN, ±Infinity, single points, all-equal series — with primitives, each is your code path. Every microchart documents and tests these in a shared fixture suite. ## Reach for visx [#reach-for-visx] * The visualization is bespoke — no catalog anywhere has your chart * You have design capacity and want d3's power with React's rendering * You are building your organization's own charting layer, at any surface size ## Reach for microcharts [#reach-for-microcharts] * The chart you need already exists in the catalog — <CatalogTotal /> word-sized types, one grammar * You want accessibility, edge cases, and design handled by default * You want static RSC output with zero client JavaScript, at <SizeMarketing /> gzip per chart ## What this page is not saying [#what-this-page-is-not-saying] * Not "visx is heavy" — 16 kB for a floor is honest for hand-built charts, and visx's modularity is well executed * Not "never build your own" — a bespoke visualization deserves primitives * The visx figure is a dated pin for one minimal composition, not a benchmark of visx overall ## Next [#next] * [When to use microcharts](/docs/when-to-use) * [Design notes](/docs/design-notes) — the decisions microcharts makes for you * [microcharts vs Recharts](/docs/vs-recharts) * [Composition](/docs/composition) — placing marks in real surfaces # When to use microcharts (/docs/when-to-use) microcharts is a set of tiny, handcrafted charts for React — built to sit *inside* an interface, where a full chart library would be too heavy and too loud. A trend after a number, a bullet in a KPI, a strip in a table cell, a mark in a streamed reply. One quiet signal, read at a glance. It is not a substitute for [Recharts](https://recharts.org), [Chart.js](https://www.chartjs.org), Nivo, ECharts, or visx. Those libraries draw surfaces that are mostly chart: axes, legends, tooltips, brush, zoom. microcharts draws the opposite: mostly words and UI, with a word-sized mark. Use a full library when the page *is* the chart. Use microcharts when the chart sits inside something you were already reading — or use both in the same product. ## Fit [#fit] | Situation | Fit | | ------------------------------------------------------------------------ | ---------------------------------------------------------------- | | Sparkline, bullet, or delta in prose, a cell, a tab, or a card | **microcharts** | | Static chart from a React Server Component with **zero** client chart JS | **microcharts** (default export) | | A model or agent emitting a chart mid-reply | **microcharts** — see [AI-native](/docs/ai) | | Full Line / Bar / Area with ticks, legend, tooltip, brush | **Recharts, Chart.js, …** | | Dense Canvas series, Chart.js plugins, analyst dashboards | **Chart.js** (or similar) | | One library for every chart in the product | Usually a **full** library; add microcharts for the inline marks | ## What this library refuses [#what-this-library-refuses] Pie, needle gauges, waffles, and similar shapes fail at word size — they are excluded on purpose. Each has a strictly-better in-catalog replacement (for example [SegmentedBar](/docs/charts/segmented-bar), [Bullet](/docs/charts/bullet), [IconArray](/docs/charts/icon-array)). See the [introduction](/docs). ## Size [#size] Every chart is imported from its own subpath and budget-gated in CI: <SizeMarketing /> gzip, **zero runtime dependencies**, static SVG from an RSC with nothing to hydrate. Accessible by default — `role="img"` with a summary generated from the data. Pinned orientation numbers for Recharts and Chart.js (version, date, method): [Full chart libraries](/docs/full-chart-libraries). Our own receipts: [Performance](/docs/performance). ## Same app, two jobs [#same-app-two-jobs] A product can use Recharts on an analytics page and a Sparkline in the table that links to it. Different import, different budget. ```tsx // dashboard panel — your full chart library <ResponsiveContainer>…</ResponsiveContainer>; // same product, table cell — microcharts import { Sparkline } from "@microcharts/react/sparkline"; <Sparkline data={row.series} width={72} height={16} dots="none" summary={false} />; ``` ## Go deeper [#go-deeper] * [React sparklines](/docs/react-sparklines) — the most common word-sized mark * [Inline charts](/docs/inline-charts) — sentences, cells, KPIs, tabs, RSC * [Full chart libraries](/docs/full-chart-libraries) — Recharts and Chart.js, side by side * Comparing a specific library? [vs Recharts](/docs/vs-recharts) · [vs Chart.js](/docs/vs-chartjs) · [vs react-sparklines](/docs/vs-react-sparklines) · [vs MUI X Sparkline](/docs/vs-mui-x-sparkline) · [vs visx](/docs/vs-visx) * [Quickstart](/docs/quickstart) — install and first chart * [Introduction](/docs) — grammar, catalog, and where they live # ABStrips (/docs/charts/ab-strips) ABStrips answers "did B beat A — and by more than the overlap?". It draws **two graded quantile strips on one shared scale**: a faint p5–95 band, a stronger p25–75 middle half, and a median dot, with row A muted and row B accent. The visible overlap of the two middle halves is the answer — and the overlap number is always in the summary, because an average delta without its spread is how A/B results lie. ```tsx <ABStrips data="{ a: Array.from({ length: 80 }, (_, i) => 130 + ((i * 13) % 44) - 22), b: Array.from({ length: 80 }, (_, i) => 116 + ((i * 13) % 44) - 22), }" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" positive="down" title="Latency A/B" width="260" height="26" /> ``` ## Install [#install] ```tsx import { ABStrips } from "@microcharts/react/ab-strips"; const control = Array.from({ length: 80 }, (_, i) => 130 + ((i * 13) % 44) - 22); const test = Array.from({ length: 80 }, (_, i) => 116 + ((i * 13) % 44) - 22); <ABStrips data={{ a: control, b: test }} positive="down" title="Latency A/B" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — an A/B experiment result in a KPI card, control vs test in an experiments table, any two-sample comparison where the spread matters. * **Avoid for** — a single distribution (BenchmarkStrip) or more than two arms (small multiples). ## Variants [#variants] ```tsx 130 + ((i * 13) % 44) - 22); const test = Array.from({ length: 80 }, (_, i) => 116 + ((i * 13) % 44) - 22); <ABStrips data={{ a: control, b: test }} seriesLabels={["Control", "Test"]} />`" > <span className="inline-flex flex-col gap-2"> <ABStrips data="{ a: Array.from({ length: 80 }, (_, i) => 130 + ((i * 13) % 44) - 22), b: Array.from({ length: 80 }, (_, i) => 116 + ((i * 13) % 44) - 22), }" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" seriesLabels="["Ctrl", "Test"]" title="Labelled" width="240" height="24" /> <ABStrips data="{ a: Array.from({ length: 80 }, (_, i) => 170 + ((i * 13) % 44) - 22), b: Array.from({ length: 80 }, (_, i) => 116 + ((i * 13) % 44) - 22), }" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" positive="down" title="Clearly separated" width="240" height="24" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <ABStrips data="{ a: [], b: [110, 120, 130] }" title="No data" width="220" height="22" /> ``` ```tsx `" > <ABStrips data="{ a: [100, 130, 145], b: Array.from({ length: 80 }, (_, i) => 116 + ((i * 13) % 44) - 22), }" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" title="Small A arm" width="220" height="26" /> ``` Either arm with zero finite values makes the whole comparison unanswerable — no strips draw, and the accessible name reads plainly **"No data."** rather than a comparison against nothing. An arm with fewer than 8 points still draws (a small sample is still the honest sample you have); only its outer band changes meaning, from the 5th–95th percentile to the plain min–max, because percentile estimates need more than a handful of points to mean anything. ## Why this default [#why-this-default] Overlap in the summary, because an average delta without spread is how A/B results lie. The strips are mandatory context — it never degrades to a bare mean bar — and the delta label never appears without the distributions behind it. When the middle halves fully overlap the summary says "no clear difference"; when they're disjoint it says "clearly separated"; and an arm with fewer than 8 points falls back to a min–max band. ## Accessibility [#accessibility] The accessible name states both medians, the delta, and the overlap — **"Test median 115 ms vs Ctrl 129 ms (-11%); middle halves overlap 35%."**. The interactive entry roves the rows (↑/↓) and the quantile edges (←/→): the median announces the delta vs the other arm, other edges announce the percentile. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ a: number[]; b: number[] }` | The two arms — raw samples, not summaries. | | `seriesLabels` | `[string, string]` | Row identities for the gutter tags + summary (default ['A', 'B']). | | `positive` | `"up" \| "down"` | Which direction of the B−A delta reads as good (colors the delta). | | `label` | `"delta" \| "none"` | Signed median delta in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # ActivityGrid (/docs/charts/activity-grid) ActivityGrid maps ordered values onto a grid of cells, each shaded by intensity. It's the contribution-graph shape: cadence, streaks, and seasonality, readable at a glance. ```tsx `" > <ActivityGrid data="[0, 1, 2, 1, 3, 4, 2, 0, 1, 3, 2, 4, 3, 1, 0, 2, 4, 3, 2, 1, 3, 0, 2, 3, 4, 1, 2, 0]" cell="11" title="Commit activity" /> ``` ## Install [#install] ```tsx import { ActivityGrid } from "@microcharts/react/activity-grid"; <ActivityGrid data={commits} title="Commits" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — daily activity, streaks and cadence, seasonality at a glance. * **Avoid for** — exact values, or precise comparison between two individual cells. Color intensity is deliberately approximate; pair it with a number when precision matters. ## Sizing [#sizing] ActivityGrid sizes from `cell` — the edge length of one square in viewBox units. Bump it to scale the whole grid, or drive the width from CSS to fill a container; the viewBox keeps the grid's aspect ratio. ## Variants [#variants] `layout="strip"` collapses to a single row for inline use. ```tsx <ActivityGrid data={commits.slice(0, 12)} layout="strip" />`" > <span className="inline-flex flex-col gap-3"> <ActivityGrid data="[0, 1, 2, 1, 3, 4, 2, 0, 1, 3, 2, 4, 3, 1, 0, 2, 4, 3, 2, 1]" cell="12" title="Grid" /> <ActivityGrid data="[0, 1, 2, 1, 3, 4, 2, 0, 1, 3, 2, 4]" layout="strip" cell="12" title="Strip" /> </span> ``` `shape` swaps the cell mark — same data, same levels, different voice: `"round"` for friendlier product surfaces, `"dot"` adds breathing room in dense strips. ```tsx <ActivityGrid data={commits.slice(0, 12)} layout="strip" shape="dot" />`" > <span className="inline-flex flex-col gap-3"> <ActivityGrid data="[0, 1, 2, 1, 3, 4, 2, 0, 1, 3, 2, 4, 3, 1, 0, 2, 4, 3, 2, 1]" shape="round" cell="12" title="Round cells" /> <ActivityGrid data="[0, 1, 2, 1, 3, 4, 2, 0, 1, 3, 2, 4]" layout="strip" shape="dot" cell="12" title="Dot strip" /> </span> ``` `anchor` aligns the grid to the real calendar: the first column pads down to the weekday of the given day (UTC), so rows read as weekdays — Monday first by default (`weekStart={0}` for Sunday). ```tsx `" > <ActivityGrid data="[2, 3, 1, 4, 2, 0, 1, 3, 2, 4, 3, 1, 0, 2, 4, 3, 2, 1]" anchor="1970-01-01" cell="12" title="Week-aligned" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <ActivityGrid data="[]" title="No history" cell="12" /> ``` ```tsx `"> <ActivityGrid data="[0, 0, 0, 0, 0, 0, 0]" title="Quiet week" cell="12" /> ``` ```tsx `"> <ActivityGrid data="[3]" title="One day" cell="12" /> ``` ## Why this default [#why-this-default] Five levels (the empty track plus four intensity steps) matches the five steps HeatCell and HeatStrip default to, and the four intensity steps share their exact opacity ramp — one calibration means "how intense" reads the same across the library, and a reader never has to relearn a color scale per chart. Only level 0 differs: here it is a faint empty track, because an activity slot with no activity is genuinely empty, not a bottom-of-scale value. Levels are discrete, never a continuous gradient: a continuous ramp implies precision a handful of pixels can't actually deliver, and discrete bins are honest about that. Monday-first weeks (`weekStart={1}`) match the ISO calendar most teams already track cadence against; `weekStart={0}` switches to Sunday-first without touching the data. Column-major fill (each column is a week, top-to-bottom) is what makes the grid read as a calendar instead of an arbitrary sequence of cells. ## Accessibility [#accessibility] Intensity is a color channel, so ActivityGrid always pairs it with a numeric summary of its total and peak — the information survives forced-colors and color-blind viewing. The interactive entry adds 2-D arrow-key navigation, announcing each cell's value as you move. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Ordered values, one per cell. | | `layout` | `"grid" \| "strip"` | 7-row calendar or single strip. | | `shape` | `"square" \| "round" \| "dot"` | Cell mark: crisp square, soft corners, or padded dot. | | `anchor` | `string \| Date` | First slot's calendar day (UTC) — pads the first column so weekday rows align. | | `weekStart` | `0 \| 1` | Start of week for anchor alignment (0 Sunday, 1 Monday). | | `cell` | `number` | Cell edge length in viewBox units. | | `domain` | `[number, number]` | Explicit range for level bucketing. | | `title` | `string` | Accessible name; joins the auto summary. | | `summary` | `string \| false` | Override or disable the auto summary. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # BalanceBeam (/docs/charts/balance-beam) BalanceBeam answers "which of two sides outweighs, and roughly by how much?" A beam tilts toward the heavier side; the direction is instant and the angle grows with the imbalance, but it **saturates** — read it as direction plus rough magnitude, not an exact ratio. The two weights are area-true (their area, not their width, is proportional to value). For a precise comparison, reach for `PairedBars` or `Delta`; this is for the glance. ```tsx <BalanceBeam data="[ { label: "Inflow", value: 620 }, { label: "Outflow", value: 480 }, ]" label="values" title="Cash flow" width="80" height="30" /> ``` ## Install [#install] ```tsx import { BalanceBeam } from "@microcharts/react/balance-beam"; <BalanceBeam data={[{ label: "Inflow", value: 620 }, { label: "Outflow", value: 480 }]} /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a buy vs sell or in vs out read in a sentence, a pro vs con weight in a KPI card, or an A-vs-B pair where direction is the story. * **Avoid for** — exact ratios (PairedBars / Delta), more than two items (MiniBar), or trends. ## Variants [#variants] ```tsx <BalanceBeam data={[{ label: "A", value: 500 }, { label: "B", value: 500 }]} />`" > <span className="inline-flex gap-6 items-center"> <BalanceBeam data="[ { label: "Inflow", value: 620 }, { label: "Outflow", value: 480 }, ]" shape="round" label="values" width="90" height="34" /> <BalanceBeam data="[ { label: "A", value: 500 }, { label: "B", value: 500 }, ]" width="70" height="28" /> </span> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, both the announced values and the in-chart numerals (`label="values"`) follow that locale's own grouping and decimal marks. ```tsx `" > <BalanceBeam data="[ { label: "Inflow", value: 62000 }, { label: "Outflow", value: 48000 }, ]" label="values" format="{ maximumFractionDigits: 0 }" locale="de-DE" width="90" height="34" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <BalanceBeam data="[ { label: "A", value: 500 }, { label: "B", value: 500 }, ]" width="70" height="28" /> ``` ```tsx `"> <BalanceBeam data="[ { label: "A", value: 0 }, { label: "B", value: 0 }, ]" width="70" height="28" /> ``` Equal values level the beam and report **"balanced"** rather than picking an arbitrary heavier side. Two zeros are the same case — the beam stays level and both weights shrink to nothing, which is honest: there is nothing to weigh. ## Why this default [#why-this-default] Ratio mode is the default because most two-sided comparisons are share-of-whole questions, and square weights are the default because circles under-read area at this size. The tilt saturates at `maxTilt` degrees — a deliberate honesty choice: past a point, a steeper beam would imply a precision the eye can't extract, so the angle levels off. Direction and rough magnitude always agree, and the two channels (tilt and weight area) never disagree. For same-scale rows that should tilt comparably, `mode="difference"` scales the imbalance by a shared `domain`. ## Accessibility [#accessibility] The accessible name states both sides and the winner — **"Inflow 620 vs Outflow 480; Inflow heavier."** — or "…; balanced." when they match. The interactive entry eases the beam to its new tilt, reveals a side's value on hover or ←/→, and announces when the heavier side flips. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `[{label,value},{label,value}]` | Exactly two items. | | `maxTilt` | `number` | Degrees at full saturation (default 12). | | `shape` | `"square" \| "round"` | Weight shape (default square). | | `mode` | `"ratio" \| "difference"` | ratio = share-of-whole; difference = absolute, scaled by domain. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # BenchmarkStrip (/docs/charts/benchmark-strip) BenchmarkStrip answers "is this value normal for its peer group?". A focal dot sits on a common scale against the peers' own **empirical** quantile bands — never a fitted distribution. There is no axis: the band is the reference frame. Small samples fall back to min–max so tail quantiles are never fiction. ```tsx `" > <BenchmarkStrip data="[ 180, 201, 237, 286, 341, 396, 443, 394, 412, 413, 398, 372, 340, 310, 205, 196, 205, 230, 271, 322, 378, 347, 391, 421, 434, 430, 412, 383, 268, 239, 221, 218, 231, 261, 306, 275, 331, 382, 422, 447, 455, 447, ]" value="312" title="Latency vs peers" width="240" height="16" /> ``` ## Install [#install] ```tsx import { BenchmarkStrip } from "@microcharts/react/benchmark-strip"; <BenchmarkStrip data={peerLatencies} value={312} format={{ style: "unit", unit: "millisecond" }} title="Latency vs peers" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a value against its cohort, per-row peer comparison in tables, SLA context. * **Avoid for** — a single trend (Sparkline) or two groups head-to-head (ABStrips). ## Variants [#variants] ```tsx // 42 peer latencies (ms) const peerLatencies = [ 180, 201, 237, 286, 341, 396, 443, 394, 412, 413, 398, 372, 340, 310, 205, 196, 205, 230, 271, 322, 378, 347, 391, 421, 434, 430, 412, 383, 268, 239, 221, 218, 231, 261, 306, 275, 331, 382, 422, 447, 455, 447, ]; <BenchmarkStrip data={peerLatencies} value={312} label="value" />`" > <span className="inline-flex flex-col gap-1.5"> <BenchmarkStrip data="[210, 260, 300, 340, 410]" value="300" range="minmax" title="Min–max" width="200" height="14" /> <BenchmarkStrip data="[ 180, 201, 237, 286, 341, 396, 443, 394, 412, 413, 398, 372, 340, 310, 205, 196, 205, 230, 271, 322, 378, 347, 391, 421, 434, 430, 412, 383, 268, 239, 221, 218, 231, 261, 306, 275, 331, 382, 422, 447, 455, 447, ]" value="312" label="value" title="Value label" width="200" height="14" /> </span> ``` ```tsx `" > <BenchmarkStrip data="[1080, 1180, 1220, 1360, 1440]" value="1240" label="value" format="{ maximumFractionDigits: 0 }" locale="de-DE" title="Localized value" width="200" height="16" /> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, both the right-gutter label and the accessible summary's numbers follow that locale's own grouping and decimal marks: the value above reads "1.240" in German, not "1,240". ## Edge cases [#edge-cases] ```tsx `" > <BenchmarkStrip data="[210, 260, 300, 340, 410]" value="300" title="5 peers" width="200" height="16" /> ``` ```tsx `"> <BenchmarkStrip data="[50, 50, 50, 50, 50, 50, 50, 50]" value="52" title="Flat cohort" width="200" height="16" /> ``` ```tsx `" > <BenchmarkStrip data="[180, 250, 300, 350, 420]" value="520" domain="[150, 400]" title="Clamped" width="200" height="16" /> ``` ## Why this default [#why-this-default] Bands come from the peers' own empirical quantiles, never a fitted distribution — the strip never implies a normal curve that the data doesn't back up. There is no axis: the band itself is the reference frame, so the focal dot's position against it is the whole read. Below 8 peers, tail quantiles (p5/p95) are statistically unreliable, so the outer band falls back to the observed min–max automatically — a deliberate honesty trade the `range` prop can also force at any sample size. A value that falls outside the plotted domain clamps to the edge and draws a small wedge rather than silently disappearing. ## Accessibility [#accessibility] The accessible name states the value, its percentile, the peer count, and the middle-half interval — **"312 — 43rd percentile of 42 peers (middle half 244.5–408.5)."** A flat cohort states it plainly instead: "52 — all 8 peers at 50." The interactive entry roves the five quantile edges with ←/→, announcing each edge's name and value (e.g. "p75: 408.5."). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Peer values. | | `value` (required) | `number` | The focal reading. | | `range` | `"p5p95" \| "minmax"` | Outer band; minmax for small samples. | | `label` | `"value" \| "percentile" \| "none"` | What the right gutter states (default percentile). | | `positive` | `"up" \| "down"` | Which side of the band is good (colors the focal dot). | | `median` | `boolean` | Center tick (default true). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # BiasStrip (/docs/charts/bias-strip) BiasStrip answers "do two ways of measuring the same thing systematically disagree?" — the agreement story a scatter can't tell. Each dot is one pair placed at its mean and its difference; the dashed line is perfect agreement, the accent line is the measured bias, and the faint band is the limits of agreement. Dots render at 75% opacity so overplot reads as density, and pairs beyond the limits are enlarged and re-inked so outliers read on shape, not color alone. ```tsx <span className="text-lg"> {"Device and reference "} <BiasStrip data="Array.from({ length: 20 }, (_, i) => ({ a: i + [1.8, 2.4, 1.5, 2.9, 2.1, 1.2, 2.6, 3.0, 1.9, 2.3, 6.5, 2.0, 1.7, 2.8, 2.2, -1.5, 2.5, 1.6, 2.7, 2.0][i], b: i, }))" title="Device vs reference" style="{ width: "3.4em", height: "1.9em" }" /> {" agree, +2 bias."} </span> ``` ## Install [#install] ```tsx import { BiasStrip } from "@microcharts/react/bias-strip"; <BiasStrip data={pairs} title="Device vs reference" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — checking whether a new instrument, method, or model agrees with a reference; instrument drift in a KPI card. * **Avoid for** — unpaired samples (use MicroScatter) or a single time series (Sparkline). A correlation plot answers "do these move together?" — but two methods can correlate perfectly and still disagree by a constant offset. BiasStrip is built for that offset: it plots the difference, so a bias jumps off the zero line where a scatter would hide it on the diagonal. ## Variants [#variants] ```tsx `" > <BiasStrip data="Array.from({ length: 20 }, (_, i) => ({ a: i + [1.8, 2.4, 1.5, 2.9, 2.1, 1.2, 2.6, 3.0, 1.9, 2.3, 6.5, 2.0, 1.7, 2.8, 2.2, -1.5, 2.5, 1.6, 2.7, 2.0][i], b: i, }))" limits="2.58" title="99% limits" style="{ width: 150, height: 84 }" /> ``` ```tsx `"> <BiasStrip data="Array.from({ length: 20 }, (_, i) => ({ a: i + [1.8, 2.4, 1.5, 2.9, 2.1, 1.2, 2.6, 3.0, 1.9, 2.3, 6.5, 2.0, 1.7, 2.8, 2.2, -1.5, 2.5, 1.6, 2.7, 2.0][i], b: i, }))" label="none" title="No caption" style="{ width: 150, height: 84 }" /> ``` ```tsx `"> <BiasStrip data="Array.from({ length: 20 }, (_, i) => ({ a: i + [1.8, 2.4, 1.5, 2.9, 2.1, 1.2, 2.6, 3.0, 1.9, 2.3, 6.5, 2.0, 1.7, 2.8, 2.2, -1.5, 2.5, 1.6, 2.7, 2.0][i], b: i, }))" r="2.5" title="Bigger dots" style="{ width: 150, height: 84 }" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <BiasStrip data="[]" title="No pairs" style="{ width: 120, height: 64 }" /> ``` ```tsx `"> <BiasStrip data="[ { a: 2, b: 0 }, { a: 3, b: 1 }, { a: 4, b: 2 }, { a: 5, b: 3 }, ]" title="Four pairs" style="{ width: 120, height: 64 }" /> ``` ```tsx `"> <BiasStrip data="[ { a: 20, b: 20 }, { a: 21, b: 21 }, { a: 22, b: 22 }, { a: 23, b: 23 }, { a: 24, b: 24 }, { a: 25, b: 25 }, ]" title="Perfect agreement" style="{ width: 120, height: 64 }" /> ``` Empty data draws just the frame with "No data." as the summary. Under 5 pairs the limits aren't meaningful, so the band and bias line drop out and only the dots and the zero reference remain — the mean difference is still stated in the summary. When the two methods agree perfectly the band collapses to a hair around the zero line rather than vanishing, so "nothing to see" still reads as a deliberate, measured result. Pairs with a non-finite value are dropped before the stats and the count; past 40 pairs the dots are uniformly downsampled for display while the bias and limits still use every pair. ## Why this default [#why-this-default] The y-axis is symmetric about zero so perfect agreement is always the visual center: a systematic offset then reads as the whole cloud drifting up or down, which is exactly the decision the chart exists to surface. The band is the classic ±1.96σ limits of agreement, and `limits` widens or tightens it (2.58 for \~99%) without ever redefining what the marks mean. Under five pairs the chart makes no interval claim at all — too little evidence to draw one honestly. ## Accessibility [#accessibility] The accessible name is the bias plus the evidence-backed agreement share — **"Bias +2.21 across 20 pairs; 90% within the limits of agreement."** — or the shorter **"Bias +2 across 4 pairs."** when there are too few pairs to draw limits. Localizing carries the number format through: with `locale="de-DE"` the same chart reads **"Bias +2,21 across 20 pairs; 90% within the limits of agreement."** The interactive entry steps pairs ordered by mean and announces each pair's mean, difference, and whether it clears the limits. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ a; b }[]` | Paired measurements. | | `limits` | `number` | k in bias ± k·σ (default 1.96 ≈ 95% limits of agreement). | | `label` | `"bias" \| "none"` | Seat-gated bias caption (default) or hidden. | | `r` | `number` | Base dot radius, clamped [1, 3]. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # BreathingDot (/docs/charts/breathing-dot) BreathingDot answers "how loaded is the system right now?" as an ambient signal. In the interactive entry the dot **pulses** — slow and small when calm, fast and large when strained — so you feel the state without reading a number. The static frame is a real chart with zero JavaScript: a core dot colored by band, and a ring whose distance from the core is the level. This is a low-precision ambient read; for an exact figure reach for `Progress` or `Sparkline`. ```tsx <BreathingDot value="0.42" title="Load" size="40" /> ``` ## Install [#install] ```tsx import { BreathingDot } from "@microcharts/react/breathing-dot"; <BreathingDot value={0.42} title="Load" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## Motion, and reduced motion [#motion-and-reduced-motion] The pulse **is** the encoding — its rate and amplitude are snapped to three named bands (calm, elevated, strained), so the motion is readable, not decorative. This is the deliberate exception to the no-looping-animation rule, allowed only because the loop parameter (the rate) is the datum. The animation is gated on two things: it pauses when the dot scrolls off-screen (a shared observer), and it never runs at all under `prefers-reduced-motion` — reduced-motion readers get exactly the static frame, where the ring's distance from the core already carries the level. The band is announced through a polite live region only when it changes, never on every pulse. ## When to use it [#when-to-use-it] * **Good for** — an ambient "how strained is it right now" read, a live status dot in a header or KPI card, or per-node load in a dense table. * **Avoid for** — an exact load figure (`Progress`, `Sparkline`), discrete events (`HeartbeatBlip`), or a trend over time (`Sparkline`). ## Sizing [#sizing] One `size` prop, in viewBox units, sets the glyph box — it defaults to `16`, about the height of a line of body text. There is no separate `width`/`height`: the dot is square, and the rendered box widens only by the gutter a `label` reserves. `fontSize` follows `size` unless you set it. ## Variants [#variants] ```tsx <BreathingDot value={0.42} label="value" />`" > <span className="inline-flex gap-6 items-center"> <BreathingDot value="0.2" size="28" /> <BreathingDot value="0.65" size="28" /> <BreathingDot value="0.92" label="value" size="28" /> <BreathingDot value="null" size="28" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <BreathingDot value="null" size="28" /> ``` ```tsx `"> <BreathingDot value="1.4" label="value" size="28" /> ``` ```tsx `"> <BreathingDot value="Number.NaN" size="28" /> ``` ```tsx `"> <BreathingDot value="0.723" label="value" locale="de-DE" size="28" /> ``` `format`/`locale` reach the `label="value"` percent numeral — always a whole percent, so a locale mostly changes digit shapes here, not grouping or decimals. The band words in the accessible summary ("calm" / "elevated" / "strained") stay in `strings` (`BreathingDotStrings`), not the number formatter. ## Why this default [#why-this-default] Three bands, because ambient motion supports about three discriminable states — more would be false precision. The band color is always doubled: by the ring offset in the static frame and by the pulse rate in motion, so the state never rests on color alone. When the value is unknown (`null` or `NaN`) the dot goes gray, drops its ring, and **never pulses** — an unknown system must not look calm. The boundary with `HeartbeatBlip`: a continuous level is a BreathingDot; discrete arriving events are a HeartbeatBlip. ## Accessibility [#accessibility] The accessible name is the level and its band word — **"Load 20% — calm."** — or **"Load unknown."** when the value is missing. The band color is never the only signal (ring offset and pulse rate double it), motion is fully gated on `prefers-reduced-motion`, and the live region announces band changes only. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | Level 0–1 (clamped). null / NaN → unknown. | | `thresholds` | `[number, number]` | calm / elevated / strained edges (default [0.5, 0.8]). | | `label` | `"value" \| "none"` | Percent numeral beside the dot. | 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](/docs/quickstart#the-shared-grammar). # BubbleRow (/docs/charts/bubble-row) BubbleRow answers "roughly how do these few magnitudes compare?" with physical presence — a row of circles whose **area** (not width) is proportional to value. Area is the weakest common channel, so this is the catalog's honest low-precision exemplar: **for a precise comparison, use `MiniBar`.** The value numerals are on by default, because a low-precision channel owes the reader the number. ```tsx <BubbleRow data="[ { label: "EMEA", value: 1240 }, { label: "AMER", value: 890 }, { label: "APAC", value: 560 }, { label: "LATAM", value: 210 }, ]" title="Market size" height="36" /> ``` ## Install [#install] ```tsx import { BubbleRow } from "@microcharts/react/bubble-row"; <BubbleRow data={regions} title="Market size" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a few magnitudes with physical presence in a sentence, a market-size or segment impression in a KPI card, or an editorial callout where the number is printed too. * **Avoid for** — precise comparison (that's `MiniBar`), trends (Sparkline), or more than about eight items. ## Variants [#variants] ```tsx <BubbleRow data={regions} label="both" />`" > <span className="inline-flex flex-col gap-4"> <BubbleRow data="[ { label: "EMEA", value: 1240 }, { label: "AMER", value: 890 }, { label: "APAC", value: 560 }, { label: "LATAM", value: 210 }, ]" align="baseline" height="36" /> <BubbleRow data="[ { label: "EMEA", value: 1240 }, { label: "AMER", value: 890 }, { label: "APAC", value: 560 }, { label: "LATAM", value: 210 }, ]" label="both" height="36" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <BubbleRow data="[]" title="No regions" height="30" /> ``` ```tsx `"> <BubbleRow data="[ { label: "EMEA", value: 1240 }, { label: "AMER", value: null }, ]" title="Missing AMER figure" height="30" /> ``` Empty data draws just the frame with "No data." as the summary. A `null` value still holds its place with a small presence ring (never a zero-radius void, and never skipped from the row) but drops its numeral — a missing figure is visibly present yet explicitly unlabeled, never faked as a zero. ## Why this default [#why-this-default] Value numerals are on by default because area lies quietly — a bubble twice the diameter is four times the area, and the eye can't reliably invert that, so the number keeps the read honest. The radius is always `r ∝ √value` with no exceptions; a linear-radius map would be a roughly squared lie. There is no sorting prop: the order is your data's order, because reordering is your statement, not the chart's. The LOW precision rating and the MiniBar steer are printed in the catalog, the machine `/catalog.json`, and this page's header — BubbleRow is the catalog's worked example of an honest low-precision admission. ## Accessibility [#accessibility] The accessible name names the extremes — **"4 items; largest EMEA at 1,240, smallest LATAM at 210."** The interactive entry roves the bubbles with ←/→ (or hover), announcing each one's exact value — **"EMEA: 1,240."** — the number the area itself can't carry. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label, value }[]` | A few non-negative magnitudes. | | `align` | `"center" \| "baseline"` | center (specimen) or baseline (weights on a shelf). | | `label` | `"value" \| "both" \| "none"` | value (default), both, or none. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Bullet (/docs/charts/bullet) Bullet compares one measured value to a target, against a backdrop of qualitative bands (poor / okay / good). It answers "are we there yet?" in a single row — ideal for progress, SLAs, budgets, and quotas. ```tsx <Bullet value="72" target="80" bands="[50, 90]" width="200" height="22" title="Quota attainment" /> ``` ## Install [#install] ```tsx import { Bullet } from "@microcharts/react/bullet"; <Bullet value={72} target={80} bands={[50, 90]} title="Quota" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — progress to a goal, a value against a target, KPIs with thresholds. * **Avoid for** — trends over time (use [Sparkline](/docs/charts/sparkline)) or distributions. ## Sizing [#sizing] `width` and `height` are viewBox units that also set the rendered pixel box — a bullet reads best wide and short. Omit them and drive the width from CSS to fill a table cell or card column; the viewBox keeps the aspect ratio. ## Variants [#variants] ```tsx `"> <Bullet value="72" target="80" bands="[50, 90]" width="220" height="22" title="Behind target" /> ``` ```tsx `"> <Bullet value="94" target="80" bands="[50, 90]" width="220" height="22" title="Ahead of target" /> ``` ```tsx `"> <Bullet value="38" target="80" width="220" height="22" title="Measure and target only" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <Bullet value="120" target="80" domain="[0, 100]" width="220" height="22" title="Over the domain" /> ``` ```tsx `" > <Bullet value="NaN" target="80" bands="[50, 90]" width="220" height="22" title="No data" /> ``` ## Why this default [#why-this-default] The qualitative bands sit lowest and graduate in shade by step, because they are context, not the answer — the measure bar has to read as the loudest mark on the row. The target is a tick, not a second bar: a distinct shape at a distinct position so "value vs target" survives grayscale print and never depends on the two colors staying apart. The measure bar itself is a thin band centered in the track (Few's proportion, not a full-height fill) so the bands stay legible on both sides of it. ## Accessibility [#accessibility] Bullet announces its value against its target — **"72 of 80 target."**. No color is required to read whether the target was met: the measure's length and the target tick encode it by position, and the qualitative bands sit behind them. The interactive entry reads the value and target on hover and focus. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The measured value. | | `target` | `number` | Target tick to compare against. | | `bands` | `number[]` | Ascending qualitative thresholds. | | `domain` | `[number, number]` | Explicit [0, max]; auto-fit otherwise. | | `label` | `"none" \| "value" \| "target" \| "both"` | Value/target readout in a right gutter (default none). | | `title` | `string` | Accessible name; joins the auto summary. | | `summary` | `string \| false` | Override or disable the auto summary. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # BumpStrip (/docs/charts/bump-strip) BumpStrip answers "where do we rank, and which way is it moving?" — position on an inverted ordinal scale, so #1 sits on top and climbing draws upward. Ranks are not values: Sparkline would lie about the distance between #2 and #3. ```tsx <BumpStrip data="[5, 5, 4, 4, 4, 3, 2, 2, 3, 2, 1, 1]" title="Category rank" width="220" height="26" /> ``` ## Install [#install] ```tsx import { BumpStrip } from "@microcharts/react/bump-strip"; <BumpStrip data={weeklyRanks} title="Category rank" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — leaderboard rows, category-rank trends in KPI cards. * **Avoid for** — continuous values (Sparkline), or more than \~15 rank levels. ## Variants [#variants] ```tsx `" > <BumpStrip data="[2, null, null, 3, 1, 1]" title="With unranked weeks" width="220" height="26" /> ``` ```tsx `"> <BumpStrip data="[8, 7, 7, 6, 4, 4, 3, 3, 2, 2, 2, 1]" maxRank="10" title="Fixed 10-rank band" width="220" height="26" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <BumpStrip data="[3]" maxRank="5" title="One period" width="140" height="26" /> ``` ```tsx `" > <BumpStrip data="[null, null, null]" title="No ranked periods" width="140" height="26" /> ``` ```tsx `" > <BumpStrip data="[3, 3, 3, 3, 3]" title="Steady at #3" width="140" height="26" /> ``` A single ranked period draws its two end labels with no visible line — there is no trajectory to show yet. An all-`null` series renders the frame with neither line nor labels; the accessible name reports it directly rather than describing a blank chart. A flat run (rank never changes) draws a level line with zero change dots, since `dots="changes"` only marks the periods where rank actually moved. ## Why this default [#why-this-default] Change dots mark only the periods where rank actually moved — flat runs stay quiet, so the eye lands on the transitions. End labels ("#5" → "#1") anchor the ordinal read without an axis. ## Accessibility [#accessibility] The accessible name is the full trajectory — **"From #8 to #1 over 12 weeks; best #1."** The interactive entry steps the periods (**"Week 7 of 12: #2."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | 1-based integer ranks; null = unranked period (gap). | | `maxRank` | `number` | Fix the band so small multiples share a rank scale. | | `dots` | `"changes" \| "none"` | Mark the moments rank actually moved. | | `label` | `"ends" \| "last" \| "none"` | "#5" → "#1" endpoint labels. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # BurnChart (/docs/charts/burn-chart) BurnChart answers "will we finish on time?". It draws the **plan** line (dashed, full length to the deadline), the **actual** line to today, and a **dotted projection** whose slope is a plain linear fit over the last few actual points — provisional by construction, never a smoothed or optimistic curve. The gap label states the signed schedule landing, because "will we finish" is a number, not a vibe. ```tsx `" > <BurnChart data="{ plan: [40, 36, 32, 28, 24, 20, 16, 12, 8, 4, 0], actual: [40, 35, 31, 27, 24, 21] }" label="gap" title="Sprint 12" width="260" height="30" /> ``` ## Install [#install] ```tsx import { BurnChart } from "@microcharts/react/burn-chart"; <BurnChart data={{ plan, actual }} title="Sprint 12" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a sprint burndown in a tab header, will-we-finish in a KPI card, plan vs actual with a projected landing. * **Avoid for** — a single progress number (Progress) or a plain series (Sparkline). ## Variants [#variants] ```tsx <BurnChart data={{ plan: [0, 4, 8, 12, 16, 20, 24, 28, 32, 36, 40], actual: [0, 5, 9, 13, 16, 19] }} mode="up" />`" > <span className="inline-flex flex-col gap-1.5"> <BurnChart data="{ plan: [40, 36, 32, 28, 24, 20, 16, 12, 8, 4, 0], actual: [40, 35, 31, 27, 24, 21] }" projection="false" title="Retrospective" width="220" height="28" /> <BurnChart data="{ plan: [0, 4, 8, 12, 16, 20, 24, 28, 32, 36, 40], actual: [0, 5, 9, 13, 16, 19] }" mode="up" title="Burn-up to scope" width="220" height="28" /> </span> ``` ```tsx `" > <BurnChart data="{ plan: [4000, 3200, 2400, 1600, 800, 0], actual: [4000, 3400, 2800, 2300] }" locale="de-DE" title="Localized point counts" width="220" height="28" /> ``` With a `locale`, the accessible summary's numbers follow that locale's own grouping — "2.300" in German, not "2,300". ## Edge cases [#edge-cases] ```tsx `" > <BurnChart data="{ plan: [], actual: [40, 35, 31, 27, 24, 21] }" title="No plan recorded" width="220" height="28" /> ``` ```tsx `" > <BurnChart data="{ plan: [40, 36, 32, 28, 24, 20], actual: [40, 40, 40, 40] }" title="Stalled" width="220" height="28" /> ``` ```tsx `"> <BurnChart data="{ plan: [40, 36, 32, 28, 24, 20], actual: [40] }" title="Day one" width="220" height="28" /> ``` With no plan (`plan: []`), the projection still runs — the fitted slope only needs `actual` — but there's nothing to compare it to, so the summary drops the "vs planned" clause. A stalled burn (`actual` flat) never reaches zero, so `finishes` is `false` and the summary states that plainly rather than extrapolating a fake landing. A single `actual` point draws no projection at all (the fit needs at least two). ## Why this default [#why-this-default] The gap label, because "will we finish" is a number, not a vibe. History is drawn solid and exact; the projection is dotted, muted, and computed as a linear fit over the last `max(2, ⌈actual/3⌉)` actual points — a stated method, never an optimistic hand-drawn curve. When the recent burn flattens, the projection never reaches zero and the summary says so outright ("not finishing at the current pace"), rather than implying a landing that isn't coming. ## Accessibility [#accessibility] The accessible name states progress against the plan and the projected landing — **"6 of 11 days in: 19 points done vs 20 planned — projected to finish 2 days late."**. The interactive entry steps the days; history announces actual vs plan, and the dotted region announces the projection. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ plan: number[]; actual: number[] }` | Remaining work per period (mode='down') or completed (mode='up'). | | `mode` | `"down" \| "up"` | Burn-down (remaining → 0, default) or burn-up (done → scope). | | `projection` | `boolean` | The dotted extrapolation to the deadline (default true). | | `work` | `string` | Work-unit noun for the summary and readout. Defaults to `strings.burnWork` ('points' in EN), so a localized bundle replaces it. | | `unit` | `string` | Period noun for the summary and gap label (default 'day'). | | `label` | `"gap" \| "none"` | Signed schedule landing vs the deadline in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # CalendarStrip (/docs/charts/calendar-strip) CalendarStrip answers "what did the last few weeks actually look like, day by day?" — week-aligned recent activity where real calendar position matters. Weekday rhythm is the read; for longer ordinal histories, use ActivityGrid. ```tsx <CalendarStrip data="Array.from({ length: 18 }, (_, i) => ({ date: `2026-06-${String(4 + i).padStart(2, "0")}`, value: i % 4 === 3 ? 0 : (i % 7) + 1, }))" end="2026-07-01" title="Deploy cadence" style="{ width: 150, height: 84 }" /> ``` ## Install [#install] ```tsx import { CalendarStrip } from "@microcharts/react/calendar-strip"; <CalendarStrip data={days} end="2026-07-01" title="Deploy cadence" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — habit/deploy cadence in KPI cards, week-aligned recent activity. * **Avoid for** — long ordinal histories (ActivityGrid), exact per-day values (MiniBar). ## Variants [#variants] ```tsx `"> <CalendarStrip data="Array.from({ length: 18 }, (_, i) => ({ date: `2026-06-${String(4 + i).padStart(2, "0")}`, value: i % 4 === 3 ? 0 : (i % 7) + 1, }))" end="2026-07-01" weeks="2" title="Two weeks" style="{ width: 150, height: 42 }" /> ``` ```tsx `"> <CalendarStrip data="Array.from({ length: 18 }, (_, i) => ({ date: `2026-06-${String(4 + i).padStart(2, "0")}`, value: i % 4 === 3 ? 0 : (i % 7) + 1, }))" end="2026-07-01" weekStart="0" title="Sunday start" style="{ width: 150, height: 84 }" /> ``` `cell`/`gap` bump the edge length and spacing directly — grid-sibling parity with ActivityGrid and GardenGrid. ```tsx `"> <CalendarStrip data="Array.from({ length: 18 }, (_, i) => ({ date: `2026-06-${String(4 + i).padStart(2, "0")}`, value: i % 4 === 3 ? 0 : (i % 7) + 1, }))" end="2026-07-01" cell="10" gap="2" title="Larger cells" style="{ width: 200, height: 112 }" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <CalendarStrip data="[]" end="2026-07-01" title="No records" style="{ width: 150, height: 84 }" /> ``` ```tsx `"> <CalendarStrip data="Array.from({ length: 14 }, (_, i) => ({ date: new Date(Date.UTC(2026, 5, 18) + i * 86400000).toISOString().slice(0, 10), value: 0, }))" end="2026-07-01" weeks="2" title="Quiet fortnight" style="{ width: 150, height: 42 }" /> ``` ## Why this default [#why-this-default] Monday start + 4 weeks: one glance covers a month of weekday rhythm without scrolling history. All date math is UTC — the same input renders identically in any host timezone, so SSR output never depends on where the server runs. `end` defaults to today but should be pinned wherever determinism matters. Empty ≠ zero: a day with no record renders as a faint outline, a day with value 0 as a filled track cell — a feed gap never masquerades as a quiet day. Future days are blank, never extrapolated. ## Accessibility [#accessibility] The accessible name counts real days — **"Active 11 of 24 days over 4 weeks."** The interactive entry walks the grid in 2-D and announces real calendar days (**"Thursday, June 11: 0."**, **"Tuesday, June 23: no data."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ date; value }[]` | Date-keyed values; duplicates sum with a dev warning. | | `weeks` | `number` | Window length in whole weeks ending at `end` (default 4). | | `end` | `string \| Date` | Last day of the window (defaults to today UTC — pin it for SSR determinism). | | `weekStart` | `0 \| 1` | Locale start-of-week (default Monday). | | `steps` | `number` | Intensity steps including the zero track (default 5). | | `shape` | `"square" \| "round" \| "dot"` | Shared cell vocabulary. | | `cell` | `number` | Cell edge length in viewBox units (default 7). | | `gap` | `number` | Gap between cells (default 1). | | `dateFormat` | `Intl.DateTimeFormatOptions \| (d: Date) => string` | (interactive) Announced day label (defaults to weekday + month + day, UTC). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # CalibrationStrip (/docs/charts/calibration-strip) CalibrationStrip answers "when this model says 70%, does it happen 70% of the time — and where is there enough data to even ask?". Each bin is a dot at its predicted probability and its observed frequency, read against the identity diagonal, with a quiet support lane underneath. Bins with too little data render open and faded, so a confident-looking dot is never backed by three samples. ```tsx <CalibrationStrip data="[ { predicted: 0.05, observed: 0.05, count: 100 }, { predicted: 0.15, observed: 0.16, count: 90 }, { predicted: 0.25, observed: 0.24, count: 80 }, { predicted: 0.35, observed: 0.36, count: 70 }, { predicted: 0.45, observed: 0.44, count: 60 }, { predicted: 0.55, observed: 0.56, count: 50 }, { predicted: 0.65, observed: 0.63, count: 40 }, { predicted: 0.7, observed: 0.52, count: 30 }, { predicted: 0.85, observed: 0.83, count: 8 }, { predicted: 0.95, observed: 0.9, count: 5 }, ]" title="Model calibration" width="300" height="44" /> ``` ## Install [#install] ```tsx import { CalibrationStrip } from "@microcharts/react/calibration-strip"; <CalibrationStrip data={reliability} title="Model calibration" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — classifier reliability / trust, probability-forecast auditing. * **Avoid for** — a single accuracy number (Delta) or where the errors go ([ConfusionGrid](/docs/charts/confusion-grid)). ## Variants [#variants] ```tsx `" > <CalibrationStrip data="[ { predicted: 0.1, observed: 0.08, count: 90 }, { predicted: 0.3, observed: 0.36, count: 70 }, { predicted: 0.5, observed: 0.44, count: 55 }, { predicted: 0.7, observed: 0.52, count: 30 }, { predicted: 0.9, observed: 0.85, count: 8 }, ]" mode="bars" title="Deviation" width="300" height="40" /> ``` ```tsx `" > <CalibrationStrip data="[ { predicted: 0.2, observed: 0.21, count: 40 }, { predicted: 0.5, observed: 0.44, count: 30 }, { predicted: 0.7, observed: 0.52, count: 30 }, ]" locale="de-DE" title="Localized probabilities" width="200" height="36" /> ``` Nothing visible changes with `locale` — this chart draws no numerals. It localizes the announced numbers: with `locale="de-DE"` the accessible name above reads "3 bins; largest gap at 0,7 predicted (observed 0,52); 0 low-support bins." — the locale's own decimal mark, not "0.7". ## Edge cases [#edge-cases] ```tsx `" > <CalibrationStrip data="[ { predicted: 0.2, observed: 0.21, count: 25 }, { predicted: 0.4, observed: 0.39, count: 25 }, { predicted: 0.6, observed: 0.63, count: 25 }, { predicted: 0.8, observed: 0.79, count: 25 }, ]" title="Well calibrated" width="200" height="36" /> ``` ```tsx `" > <CalibrationStrip data="[ { predicted: 0.3, observed: 0.2, count: 3 }, { predicted: 0.6, observed: 0.7, count: 4 }, { predicted: 0.9, observed: 0.6, count: 3 }, ]" title="Sparse bins" width="200" height="36" /> ``` ## Why this default [#why-this-default] Dots plus an always-on support lane because "how sure" and "based on how much" must travel together — a reliability read without support disclosure is exactly the failure this chart exists to prevent. Low-support bins are drawn open and faded and the count is never disableable. There is deliberately no single-number calibration score (ECE) rendered or announced: one number would hide precisely the per-bin structure the chart exists to show. ## Accessibility [#accessibility] The accessible name reports the worst miscalibration and the support gaps — **"5 bins; largest gap at 0.7 predicted (observed 0.52); 1 low-support bin."** The interactive entry roves the bins with ←/→, announcing each bin's predicted and observed probability and its sample support. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `RawPair[] \| BinnedRow[]` | Raw pairs or pre-binned reliability rows. | | `bins` | `number` | Uniform bin count for raw input. | | `minSupport` | `number` | Below this a bin renders low-confidence. | | `mode` | `"dots" \| "bars"` | Bars draw signed deviation columns. | | `color` | `string` | Accent stroke/fill override. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # ChangePoint (/docs/charts/change-point) ChangePoint answers "when did the behavior change level?". It shades alternating regimes, draws a per-regime mean, and marks the break where one level became another — because a spike means nothing without the regime it broke. The detector is a **documented heuristic, not statistics**; for production anomaly pipelines, pass your own break indices and the chart becomes pure annotation. ```tsx `" > <ChangePoint data="[30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48]" label="delta" title="Error rate" width="200" height="24" /> ``` ## Install [#install] ```tsx import { ChangePoint } from "@microcharts/react/change-point"; <ChangePoint data={errors} label="delta" title="Error rate" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — context for an anomaly, an error rate / latency / cost that stepped to a new level, or annotating a known deploy or incident (pass explicit `breaks`). * **Avoid for** — a gradual trend (Sparkline) or a plain time series with no regime question. ## Variants [#variants] ```tsx <ChangePoint data={[20, 21, 23, 24, 26, 27, 29, 30, 32, 33, 35, 36, 38, 39, 41, 42, 44, 45, 47, 48]} />`" > <span className="inline-flex gap-4 items-center"> <ChangePoint data="[30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48]" breaks="[14]" width="150" height="22" /> <ChangePoint data="[20, 21, 23, 24, 26, 27, 29, 30, 32, 33, 35, 36, 38, 39, 41, 42, 44, 45, 47, 48]" width="150" height="22" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <ChangePoint data="[3000, 3000, 3000, 3000, 3000, 3000, 3000, 5200, 5200, 5200, 5200, 5200, 5200]" label="delta" locale="de-DE" title="Localized regime means" width="200" height="24" /> ``` ```tsx `" > <ChangePoint data="[10, 10, 10, 50, 50, 50]" title="Six points" width="150" height="22" /> ``` ```tsx `"> <ChangePoint data="[42]" title="One point" width="100" height="22" /> ``` With a `locale`, the summary and delta label format their numbers in that locale's own grouping and decimal marks. Auto-detection (`breaks="auto"`) only runs at 8 or more points — a six-point series with an obvious jump still renders as one flat, unbroken regime unless you pass `breaks` explicitly; this is deliberate, since a two-segment fit on that few points is mostly noise. A single point has no line to draw and no break to find; `data={[]}` renders the frame with the "no data" summary and no marks. ## Why this default [#why-this-default] Context for every anomaly — the shading names the regime a value belongs to, and the break marks where the level truly changed, so a reader sees "errors stepped up here" rather than "errors are high". The detector is a **labelled heuristic**: a two-segment mean-shift found by binary segmentation, accepted only when the split both cuts the variance enough and clears an effect-size threshold, so a constant series shows no break. It is a mean-shift test, not a trend test: a steady ramp is still fitted as two regimes (the ramp variant above reports a shift around point 10), so pass `breaks` explicitly when you already know the series is trending rather than stepping. For anomaly pipelines that already know their breakpoints, `breaks={[…]}` turns the detection off and the chart becomes a faithful annotation. ## Accessibility [#accessibility] The accessible name states the shift, the break, the regime means, and what happened after — **"Level shifted up 60% around point 14 (mean 30 → 48); stable since."** — or, with no detected shift, "No clear level shift across N points." The interactive entry steps the points with ←/→ (value + regime) and cycles the breaks with Tab, each announcing its mean shift. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | A single series. | | `breaks` | `"auto" \| number[]` | Explicit indices override the heuristic entirely — the production path. | | `maxItems` | `number` | Max detected breaks (1–3). More regimes stop being glanceable. | | `means` | `boolean` | Per-regime mean hairlines (default true). | | `label` | `"delta" \| "none"` | Signed % across the most recent break, in a gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # CitySkyline (/docs/charts/city-skyline) CitySkyline answers "how do these groups compare on size, and how activated is each?" — two variables in one row. **Height** is the primary, precise channel (zero-anchored bars, like a MiniBar); the **lit-window fraction** is a secondary, low-precision channel you read as "mostly lit, half lit, or dark", not a number. Omit `lit` everywhere and it's a plain, honest bar row. ```tsx `" > <CitySkyline data="[{ label: "Platform", value: 46, lit: 0.7 }, { label: "Core", value: 32, lit: 0.5 }, { label: "Web", value: 28, lit: 0.9 }, { label: "API", value: 40, lit: 0.3 }, { label: "Data", value: 18, lit: 0.6 }]" unit="teams" title="Team sizes" bw="16" gap="6" height="40" /> ``` ## Install [#install] ```tsx import { CitySkyline } from "@microcharts/react/city-skyline"; <CitySkyline data={teams} unit="teams" title="Team sizes" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — team or region size plus an activation read, an org KPI where two variables are the story, or a per-BU comparison with utilization. * **Avoid for** — a single variable (that's `MiniBar`), precise activation reads, or more than about eight groups. ## Variants [#variants] ```tsx ({ label, value }))} /> <CitySkyline data={teams} label="value" />`" > <span className="inline-flex gap-8 items-end"> <CitySkyline data="[ { label: "A", value: 46 }, { label: "B", value: 32 }, { label: "C", value: 40 }, ]" bw="14" gap="5" height="30" /> <CitySkyline data="[ { label: "A", value: 46, lit: 0.7 }, { label: "B", value: 32, lit: 0.4 }, ]" label="value" bw="16" gap="6" height="34" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <CitySkyline data="[ { label: "A", value: 30, lit: 0.8 }, { label: "B", value: 30, lit: 0.4 }, { label: "C", value: 30, lit: 0 }, ]" title="Flat skyline" bw="16" gap="6" height="36" /> ``` ```tsx `" > <CitySkyline data="[ { label: "big", value: 40, lit: 0.8 }, { label: "tiny", value: 2, lit: 0.9 }, ]" title="Secondary channel drops out first" bw="16" gap="6" height="36" /> ``` ## Why this default [#why-this-default] Windows come on when `lit` is present, because the two-variable read is exactly why this beats a `MiniBar`. Heights are always zero-anchored bars; the lit windows are quantized to the window count and filled bottom-up, so the activation reads as a fill level. There is no roofline variation, no antennas, and nothing encoded in building width — width, roof, and ground are constants, because every mark must earn its place. The secondary channel drops out before the primary: a building too short for any window row is a solid tower, and its `lit` still shows in the per-building readout on hover or keyboard focus. ## Accessibility [#accessibility] The accessible name names the count and the tallest — **"3 groups; tallest A at 46."** The interactive entry roves the buildings with ←/→ (or hover), announcing each on its own: on the team demo at the top of this page, Platform reads "Platform: 46; 70% lit." — the size precisely, the activation as a percent. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label, value, lit? }[]` | value = height; lit = 0–1 window fraction. | | `labels` | `boolean` | Category labels under the buildings. | | `ground` | `boolean` | The baseline hairline (default true). | | `label` | `"none" \| "value"` | Numeral above each building. | | `unit` | `string` | Category noun for the summary (default 'groups'). | | `bw` | `number` | Building width in viewBox units (default 9). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # CohortTriangle (/docs/charts/cohort-triangle) CohortTriangle stacks retention cohorts as rows and ages as columns, shading each cell by a discrete retention level. Because newer vintages have been observed for fewer ages, the block takes the classic **triangle** shape — and reading down a column compares every cohort at the **same maturity**, which is where "who retains worst" actually lives. ```tsx <CohortTriangle data="[ { label: "Jan", values: [1, 0.62, 0.48, 0.41, 0.38, 0.37] }, { label: "Feb", values: [1, 0.58, 0.44, 0.38, 0.35] }, { label: "Mar", values: [1, 0.47, 0.36, 0.31] }, { label: "Apr", values: [1, 0.55, 0.42] }, { label: "May", values: [1, 0.52] }, ]" cell="16" unit="month" title="Monthly retention" /> ``` ## Install [#install] ```tsx import { CohortTriangle } from "@microcharts/react/cohort-triangle"; <CohortTriangle data={cohorts} unit="month" title="Monthly retention" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — monthly or weekly cohorts side by side, spotting which vintage decays worst, reading retention at equal maturity in a KPI card. * **Avoid for** — exact per-cell values (color intensity is deliberately approximate; pair it with a number when precision matters), or a single cohort's decay, where [RetentionCurve](/docs/charts/retention-curve) draws the curve directly. ## Sizing [#sizing] CohortTriangle sizes from `cell` — the edge length of one square in viewBox units. Bump it to scale the whole grid; the viewBox keeps the aspect ratio when CSS drives the width. Row labels seat automatically and drop out cleanly below roughly an 8-unit cell. ## Variants [#variants] Row labels are on by default. Turn them off for a dense, glanceable block, or `highlight` one vintage to anchor the equal-maturity comparison. ```tsx <CohortTriangle data={cohorts} labels={false} cell={9} />`" > <span className="inline-flex flex-col gap-3"> <CohortTriangle data="[ { label: "Jan", values: [1, 0.62, 0.48, 0.41, 0.38, 0.37] }, { label: "Feb", values: [1, 0.58, 0.44, 0.38, 0.35] }, { label: "Mar", values: [1, 0.47, 0.36, 0.31] }, { label: "Apr", values: [1, 0.55, 0.42] }, { label: "May", values: [1, 0.52] }, ]" cell="16" unit="month" highlight="Mar" title="Worst vintage ringed" /> <CohortTriangle data="[ { label: "Jan", values: [1, 0.62, 0.48, 0.41, 0.38, 0.37] }, { label: "Feb", values: [1, 0.58, 0.44, 0.38, 0.35] }, { label: "Mar", values: [1, 0.47, 0.36, 0.31] }, { label: "Apr", values: [1, 0.55, 0.42] }, { label: "May", values: [1, 0.52] }, ]" labels="false" cell="9" title="Dense block" /> </span> ``` The `unit` prop renames the age columns in the summary and announcements — `"month"`, `"week"`, `"day"`, whatever the cohort period is. ## Edge cases [#edge-cases] ```tsx `"> <CohortTriangle data="[{ label: "Jan", values: [1, 0.6, 0.45, 0.4] }]" unit="month" cell="16" title="One cohort" /> ``` ```tsx `" > <CohortTriangle data="[{ label: "Jan", values: [1, 0.6, null, 0.4] }]" cell="16" title="Gap slot" /> ``` ```tsx `" > <CohortTriangle data="[ { label: "Jan", values: [100, 62, 48] }, { label: "Feb", values: [100, 47] }, ]" cell="16" unit="month" title="Percent-scale input" /> ``` ```tsx `" > <CohortTriangle data="[ { label: "Jan", values: [1, 0.62, 0.48] }, { label: "Feb", values: [1, 0.47] }, ]" cell="16" unit="month" locale="de-DE" title="Localized retention" /> ``` A single cohort skips the comparison and just states its first reading. A `null` (or any non-finite) value renders as an outlined **gap** slot — a "measured nothing here" cell, never a shaded 0%. `data` accepts either a 0–1 fraction or a 0–100 percent series — whichever the max value implies — so a raw percent export renders identically to its fraction form. With a `locale`, every announced number follows that locale's own formatting. ## Why this default [#why-this-default] Rows are cohorts in input order and columns are age, because the decision — *which vintage retains worst* — is a **vertical** read at a fixed age, and the ragged right edge falls out naturally from newer cohorts simply having fewer observed ages. Intensity is quantized to five discrete levels (never a continuous ramp): a smooth gradient would imply a precision a handful of pixels cannot deliver. A worst-vintage flag is **off** by default — the marks stay honest and the summary names the laggard in words instead of painting a verdict onto the grid. ## Accessibility [#accessibility] Intensity is a color channel, so CohortTriangle always pairs it with a numeric summary that compares at equal maturity — **"5 cohorts; at month 1, Mar retains worst (47%); newest May starts at 100%."**. Direction is stated in words, never by color alone, so it survives forced-colors and color-blind viewing. The interactive entry adds 2-D arrow-key navigation, announcing each cell as *"Feb cohort, month 1: 58%"* as you move. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label, values }[]` | One row per cohort; values[i] = retention at age i (0–1 or 0–100, ragged). | | `labels` | `boolean` | Cohort labels in a left gutter (default true; drops at tiny cell sizes). | | `highlight` | `string` | Ring the cohort with this label — the comparison focus. | | `unit` | `string` | Age-column noun for the summary (default "period"). | | `cell` | `number` | Cell edge length in viewBox units. | | `title` | `string` | Accessible name; joins the auto summary. | | `summary` | `string \| false` | Override or disable the auto summary. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # CometTrail (/docs/charts/comet-trail) CometTrail answers "where is the value now, and where has it just been?" A bright head dot marks the current value; behind it, a trail of recent points fades out with age, like a comet. In the interactive entry the head eases to each new value and the old head decays into the trail, so a live stream draws a comet and a stall goes still. Opacity encodes **age only** — the y position does the value — so the trail is recency context, never data you have to decode. ```tsx <CometTrail data="[40, 45, 50, 55, 60, 65, 70, 72, 75, 78, 80, 84, 87]" title="Latency" width="90" /> ``` ## Install [#install] ```tsx import { CometTrail } from "@microcharts/react/comet-trail"; <CometTrail data={rollingWindow} title="Latency" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## Motion, and reduced motion [#motion-and-reduced-motion] Motion happens **only on a data change** — there is no idle loop. When a new value arrives the head eases (\~200 ms, the library's canonical strong ease-out) from its old position to the new one and the previous head steps down into the trail; a continuous stream produces the comet, a stalled stream simply goes still, which is itself the signal (staleness reads as stillness). The dot jumps to the truth, eased — it never simulates phantom positions between updates. Under `prefers-reduced-motion` the head repositions instantly (the static encoding is already complete), and the same is true off-screen — one shared viewport check means the ease only runs while the chart is actually in view. ## When to use it [#when-to-use-it] * **Good for** — a live price or metric with a little recency context, a realtime KPI that should show momentum, or per-stream "where is it now" in a table. * **Avoid for** — the full history (`Sparkline`), an exact multi-point comparison (`Sparkline`, `DotPlot`), or discrete events (`HeartbeatBlip`). ## Sizing [#sizing] `width` and `height` are viewBox units that also set the rendered pixel box — they default to `60 × 16`, sized to sit in a table cell or beside a line of text. Omit them and drive the width from CSS to fill a column; the viewBox keeps the aspect ratio. `trail` controls how many recent points the tail carries, which is a density decision rather than a size one. ## Variants [#variants] ```tsx <CometTrail data={window} label="none" />`" > <span className="inline-flex gap-6 items-center"> <CometTrail data="[40, 45, 50, 55, 60, 65, 70, 72, 75, 78, 80, 84, 87]" trail="6" width="100" summary="false" /> <CometTrail data="[40, 45, 50, 55, 60, 65, 70, 72, 75, 78, 80, 84, 87]" label="none" width="100" summary="false" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <CometTrail data="[]" title="No stream yet" width="90" /> ``` ```tsx `"> <CometTrail data="[52]" title="First reading" width="90" /> ``` ```tsx `" > <CometTrail data="[40, 55, 48, 62]" trail="20" title="Short stream" width="90" /> ``` Empty data draws just the frame, with "No data." as the summary. A single point has no trail to fade — just the head and "Now 52." A `trail` larger than the data never backfills or pads: the trail simply shows every point there is. ## Why this default [#why-this-default] `label="last"` is on because a live value without its number is a mood, not a measurement — the whole point is knowing where it is now. Opacity encodes age and nothing else, so changing `trail` gives you more or less recency context without ever changing the head read. The trail is capped at 20 points: past that it stops being a trail and becomes a sparkline, which is the better tool for the full history. ## Accessibility [#accessibility] The accessible name is the now-value and the recent trend — **"Now 62, rising over the last 3 updates."** — or just the value when there is a single point, as in the edge case above: **"Now 52."** Arrow keys step back through the trail ("3 updates ago: 78.") and return toward now; motion is gated on `prefers-reduced-motion`, and the trail opacity is age, never a value you must read from fading. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | The rolling window, oldest → newest (last = now). | | `trail` | `number` | Points kept visible (default 12, cap 20). | | `label` | `"last" \| "none"` | Numeral after the head (default last). | 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](/docs/quickstart#the-shared-grammar). # ConfusionGrid (/docs/charts/confusion-grid) ConfusionGrid answers "where do the errors go?" — the one thing accuracy-as-a-number hides. Rows are the actual class, columns the predicted class, and each cell's ink is the row-normalized share: of the actual X, where did the predictions go? The diagonal (agreement) is accented by shape, never by colour, so good and bad are positions on the grid, not hues. The one-line key — rows actual, columns predicted — belongs next to every example. ```tsx `" > <ConfusionGrid data="{ labels: ["A", "B", "C"], counts: [[70, 8, 2], [6, 62, 12], [3, 9, 58]] }" label="accuracy" title="Classifier" size="120" /> ``` ## Install [#install] ```tsx import { ConfusionGrid } from "@microcharts/react/confusion-grid"; <ConfusionGrid data={counts} title="Classifier" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — classifier evaluation, and any paired-classification agreement (triage vs outcome, plan vs actual, rater A vs rater B). * **Avoid for** — a single accuracy number (Delta) or more than four classes (use a full-size heatmap). ## Variants [#variants] ```tsx `"> <ConfusionGrid data="{ labels: ["A", "B", "C"], counts: [ [70, 8, 2], [6, 40, 34], [3, 9, 58], ], }" accent="errors" title="Worst confusion" size="110" /> ``` ## Edge cases [#edge-cases] ```tsx 4 clamps to the first four classes (dev-warns)" code="`<ConfusionGrid data={{ labels: ["A", "B", "C", "D", "E"], counts: [ [40, 3, 1, 0, 2], [4, 38, 2, 1, 0], [1, 3, 44, 2, 1], [0, 2, 3, 36, 4], [2, 1, 0, 3, 41], ], }} title="5 classes" />`" > <ConfusionGrid data="{ labels: ["A", "B", "C", "D", "E"], counts: [ [40, 3, 1, 0, 2], [4, 38, 2, 1, 0], [1, 3, 44, 2, 1], [0, 2, 3, 36, 4], [2, 1, 0, 3, 41], ], }" title="5 classes" size="110" /> ``` A fifth class doesn't grow the grid — legibility caps at 4×4, so a `k` of 5 or more clamps to the first four labels and rows/columns, with a dev warning steering to a full-size heatmap. The grid never silently drops classes in production (the warning is dev-only), but the render itself does truncate; pass pre-filtered `labels`/`counts` if you need a specific four. ```tsx `" > <ConfusionGrid data="{ labels: ["cat", "dog"], counts: [ [40, 10], [0, 0], ], }" title="No dog samples" size="90" /> ``` ## Why this default [#why-this-default] The row view answers the question practitioners actually ask — "of the real cats, how many did we call dogs?" — so row-normalization is stated in the summary phrasing ("% of cats") and the denominator travels with every number. Accuracy is off by default and never rendered without the grid: the number may not leave its context. The diagonal accent is a shape (an inset stroke), and the ink ramp is identical for agreement and error cells — good and bad are positions, not colours, which is what keeps it readable under forced colours. ## Accessibility [#accessibility] The accessible name states accuracy and the worst confusion, with the row-normalized denominator carried in the phrasing — the grid at the top of this page reads **"Accuracy 73%. Most confused: B predicted as C (43% of Bs)."** A perfect classifier reads **"Accuracy 100%. No confusion."**, and a class with no samples is named rather than hidden — the `cat`/`dog` example above reads **"Accuracy 80%. Most confused: cat predicted as dog (20% of cats). No dog samples."** The interactive entry roves the cells with the arrow keys (Home and End jump to the two ends of the diagonal), announcing each cell's actual and predicted class as a share of the actual class. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ labels, counts }` | k×k matrix; rows actual, columns predicted. | | `normalize` | `"row" \| "none"` | Row = recall view (default). | | `accent` | `"diagonal" \| "errors"` | Agreement or the worst confusion. | | `label` | `"accuracy" \| "none"` | Overall accuracy in the gutter (opt-in). | | `shape` | `"square" \| "round"` | Cell shape from the shared vocabulary (default 'square'). | | `color` | `string` | Accent fill override. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Constellation (/docs/charts/constellation) Constellation answers "when did the rare events happen, and how big were they?" Each event is a dot placed by time (x) and value (y), with an optional magnitude driving its area-true size. A hairline line connects the events in time order, so the sequence of a handful of incidents reads at a glance. It is built for *rare* events — a dozen or fewer; dense streams belong to `Seismogram` or `EventTimeline`. ```tsx ["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep"][x]; <Constellation data={[ { x: 0, y: 40, m: 2 }, { x: 2, y: 90, m: 7 }, { x: 5, y: 30, m: 3 }, { x: 8, y: 65, m: 5 }, ]} xFormat={month} title="Incidents" />`" > <Constellation data="[{ x: 0, y: 40, m: 2 }, { x: 2, y: 90, m: 7 }, { x: 5, y: 30, m: 3 }, { x: 8, y: 65, m: 5 }]" xFormat="(x) => ["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep"][x]" title="Incidents" width="120" height="34" /> ``` ## Install [#install] ```tsx import { Constellation } from "@microcharts/react/constellation"; <Constellation data={[ { x: 0, y: 40, m: 2 }, { x: 2, y: 90, m: 7 }, { x: 5, y: 30, m: 3 }, { x: 8, y: 65, m: 5 }, ]} title="Incidents" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — sparse incidents or outages on a timeline, milestones carrying a magnitude, or any rare events where the sequence is the story. * **Avoid for** — dense event streams (`Seismogram`, `EventTimeline`), a continuous trend (`Sparkline`), or precise value comparison (dot area is a low-precision channel). ## Variants [#variants] ```tsx <Constellation data={events} connect={false} />`" > <span className="inline-flex gap-6 items-center"> <Constellation data="[ { x: 0, y: 40, m: 2 }, { x: 2, y: 90, m: 7 }, { x: 5, y: 30, m: 3 }, { x: 8, y: 65, m: 5 }, ]" label="max" width="110" height="32" summary="false" /> <Constellation data="[ { x: 0, y: 40, m: 2 }, { x: 2, y: 90, m: 7 }, { x: 5, y: 30, m: 3 }, { x: 8, y: 65, m: 5 }, ]" connect="false" width="110" height="32" summary="false" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <Constellation data="[]" title="No incidents" width="110" height="28" /> ``` ```tsx `"> <Constellation data="[{ x: 3, y: 40 }]" title="One incident" width="110" height="28" /> ``` ```tsx `"> <Constellation data="[{ x: 0 }, { x: 2 }, { x: 5 }, { x: 8 }]" title="No values" width="110" height="28" /> ``` Empty data draws no marks at all — just the sized box — with "No data." as the summary. A single event has no line to draw — just one dot, and the summary says "1 event at …" rather than forcing a range. When every point omits `y`, the vertical spread is deterministic jitter for legibility only — the summary and the interactive readout never mention it, and the connector's slope carries no meaning in that mode. ## Why this default [#why-this-default] The chronology line is on by default because the sequence is usually the story of rare events — you want to see the order and rhythm, not just a scatter. Dot size is *area-true* (`r ∝ √m`), because area is how the eye reads magnitude; it is a deliberately low-precision channel, so the number lives in the summary and the hover readout, not in a size you are asked to measure. When no event carries a value, the vertical position is **deterministic jitter that encodes nothing** — it only spreads the dots so they do not stack. In that case the connector's slope is meaningless (it still runs in time order), and the summary never mentions vertical position. Time is sacred: the x position is never jittered, so simultaneous events sit at the same x. ## Accessibility [#accessibility] The accessible name states the count, the span, and the largest event — **"4 events between 0 and 8; largest at 8."** The interactive entry lets you arrow through the events chronologically, each announced with its time, value, and magnitude through a polite live region; a hover readout shows the same. Magnitude is redundant with the dot size, never carried by it alone. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ x: number; y?: number; m?: number }[]` | Events: x = time, y = value, m = magnitude (area-true size). | | `connect` | `boolean` | The faint chronology line (default true). | | `label` | `"max" \| "none"` | Numeral at the largest event. | | `xFormat` | `(x: number) => string` | Formats time for the summary (e.g. a month name). | | `xDomain` | `[number, number]` | Time (x) extent (default: data extent). | | `rBase` | `number` | Base dot radius in viewBox units (default 1.6). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # ControlStrip (/docs/charts/control-strip) ControlStrip answers "is the process in control — or did something leave the band?". It's a Shewhart individuals chart: the control band is the process center ± 3σ̂, where **σ̂ = mean moving range ÷ 1.128** — the individuals estimator, stated outright (sample SD is not used; it inflates the limits under drift). In-control points are bare vertices; only out-of-control points are marked (ringed, in the negative color), because an in-control process should look boring. ```tsx `" > <ControlStrip data="[74, 73, 75, 74, 76, 73, 74, 75, 74, 73, 82, 74, 75, 73, 74, 76, 74, 73, 75, 74, 66, 74, 75, 74, 73, 76, 74, 75, 74, 73]" title="Line 3 fill weight" width="260" height="26" /> ``` ## Install [#install] ```tsx import { ControlStrip } from "@microcharts/react/control-strip"; <ControlStrip data={weights} title="Line 3 fill weight" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a production line or metric in a table cell, an SPC control chart in a KPI card, flagging out-of-control excursions at a glance. * **Avoid for** — a plain trend (Sparkline) or a strongly trending series (ChangePoint — control limits assume a stationary process). ## Variants [#variants] ```tsx <ControlStrip data={weights} dots="all" />`" > <span className="inline-flex flex-col gap-1.5"> <ControlStrip data="[ 74, 73, 75, 74, 76, 73, 74, 75, 74, 73, 82, 74, 75, 73, 74, 76, 74, 73, 75, 74, 66, 74, 75, 74, 73, 76, 74, 75, 74, 73, ]" rules="we" title="WE rules" width="220" height="24" /> <ControlStrip data="[74, 73, 75, 74, 76, 73, 74, 75, 74, 73, 82, 74, 75, 73, 74, 76]" dots="all" title="All dots" width="220" height="24" /> </span> ``` ```tsx `" > <ControlStrip data="[2.4, 2.5, 2.45, 2.55, 2.5, 2.6, 2.4, 2.5, 2.45, 2.9, 2.5, 2.55]" format="{ maximumFractionDigits: 1 }" locale="de-DE" title="Localized limits" width="220" height="24" /> ``` The chart draws no in-chart numbers, so `format`/`locale` shape the accessible summary and the interactive announcements — the strip above reads "All 12 points within control limits (center 2,5, limits 2,1–2,9)." with German decimal commas. ## Edge cases [#edge-cases] ```tsx `" > <ControlStrip data="[10, 11, 9, 10, 12, 8]" title="Provisional" width="160" height="22" /> ``` ```tsx `" > <ControlStrip data="[5, 5, 5, 5]" title="Constant" width="160" height="22" /> ``` ## Why this default [#why-this-default] Flag only the out-of-band points, because an in-control process should look boring — the eye should land on the exception, not scan every dot. The σ̂ estimator is the moving-range one (`MR̄ / 1.128`), never a vague "±3 sigma"; `limits="percentile"` states its exact quantiles for skewed processes. Western Electric rules are conventions, so the implemented subset is enumerated (WE-1 beyond 3σ, WE-2 two-of-three beyond 2σ, WE-4 eight on one side) and none fires silently. With fewer than 10 points the band is dashed and the summary says "limits provisional". ## Accessibility [#accessibility] The accessible name states the excursion count, the center, and the limits — **"2 of 30 points outside control limits (center 74.17, limits 67.84–80.49)."**; an in-control run reads "All N points within control limits …". The interactive entry steps the points and out-of-control points announce which limit they crossed. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Sequential measurements. | | `limits` | `"sigma" \| "percentile"` | ±3σ̂ (default) or empirical p0.135/p99.865 for skewed processes. | | `baseline` | `number` | Known process center from a reference period (else = mean). | | `rules` | `"none" \| "we"` | Western Electric secondary run rules (WE-1/2/4 subset). | | `dots` | `"out" \| "all" \| "none"` | Mark only out-of-control points (default), every point, or none. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # CoverageStrip (/docs/charts/coverage-strip) CoverageStrip answers "can I trust this data — where was nothing measured?". Measured slots are filled; gaps are hollow with a hairline outline. The distinction between `null` (no measurement) and `0` (a measured zero) is the whole chart, and it is carried by **shape**, so it survives forced-colors and print. Nothing is ever interpolated across a gap. ```tsx <CoverageStrip data="[3, 4, null, 5, 0, null, null, 6, 8, 7, null, 9, 11, 10]" expected="18" label="percent" title="Sensor uptime" width="240" height="16" /> ``` ## Install [#install] ```tsx import { CoverageStrip } from "@microcharts/react/coverage-strip"; <CoverageStrip data={readings} expected={18} label="percent" title="Sensor uptime" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — data-quality cells beside a metric, sensor-uptime rows, trailing-gap detection. * **Avoid for** — magnitude over time (HeatStrip) or exact values (Sparkline). ## Variants [#variants] ```tsx <CoverageStrip data={readings} shape="round" />`" > <span className="inline-flex flex-col gap-1.5"> <CoverageStrip data="[3, 4, null, 5, 0, null, 6, 8, 7, null, 9, 11]" mode="intensity" domain="[0, 12]" title="Intensity" width="200" height="12" /> <CoverageStrip data="[3, 4, null, 5, 0, null, 6, 8, 7, null, 9, 11]" shape="round" title="Round" width="200" height="12" /> </span> ``` ```tsx `" > <CoverageStrip data="[3, 4, null, 5, 0, null, null, 6, 8, 7, null, 9, 11, 10]" expected="18" label="percent" locale="de-DE" title="Localized coverage" width="200" height="14" /> ``` `locale` formats the coverage percentage in the gutter and the accessible summary — the strip above reads "56 %" (German percent spacing) instead of "56%". `format` shapes the measured values the interactive entry announces. ## Edge cases [#edge-cases] ```tsx `" > <CoverageStrip data="[1, 1, 1]" expected="8" label="percent" title="Trailing gap" width="180" height="16" /> ``` ```tsx `"> <CoverageStrip data="[3, 0, null, 5]" title="Zero vs missing" width="100" height="16" /> ``` ```tsx `"> <CoverageStrip data="[]" title="Empty" width="80" height="16" /> ``` ## Why this default [#why-this-default] Shape carries the presence/absence distinction, not just color, so it survives forced-colors and print. A measured `0` is a filled cell like any other value; only `null` (no record) is hollow — the two never look the same. `expected` lets a trailing shortfall count as coverage loss: a feed that simply stops reporting is the worst gap of all, so it isn't silently dropped from the denominator. Nothing is ever interpolated across a gap — a missing slot stays visibly empty rather than being smoothed into its neighbors. ## Accessibility [#accessibility] The accessible name states how many slots were measured, the coverage percentage, and the longest gap — **"10 of 18 slots measured (56 %); longest gap 4 slots."** An empty series states "No data." instead. The interactive entry roves slots with ←/→, announcing each one as a measured value or "no measurement". The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | Time-ordered slots; null = no measurement, 0 = a measured zero. | | `expected` | `number` | Slots the window should contain — lets trailing missingness count. | | `mode` | `"binary" \| "intensity"` | Presence only (default), or shade measured cells by value. | | `steps` | `number` | Intensity granularity (default 5). | | `shape` | `"square" \| "round" \| "dot"` | Cell shape from the shared vocabulary (default 'square'). | | `label` | `"percent" \| "none"` | State the coverage number in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # CyclePlot (/docs/charts/cycle-plot) CyclePlot answers "what repeats beneath the trend — and is any slot itself drifting?". The series is reshaped into `period` slots (7 for weekdays, 12 for months); each slot shows its own raw values across cycles as a muted polyline in **time order**, plus a mean tick, and the accent spine connects the slot means. Seasonality (the spine) and drift (the within-slot lines) are different questions of the same data — so they never share a mark. ```tsx `" > <CyclePlot data="[38, 40, 45, 48, 52, 61, 44, 38, 42, 45, 48, 52, 61, 44, 38, 44, 45, 48, 52, 61, 44, 38, 46, 45, 48, 52, 61, 44, 38, 48, 45, 48, 52, 61, 44, 38, 50, 45, 48, 52, 61, 44]" period="7" slots="["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]" cycleUnit="weeks" title="Weekly shape" width="200" height="40" /> ``` ## Install [#install] ```tsx import { CyclePlot } from "@microcharts/react/cycle-plot"; <CyclePlot data={daily} period={7} slots={weekdays} cycleUnit="weeks" title="Weekly shape" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a KPI card that says "the week has a shape", weekday traffic / hourly load / monthly sales seasonality, or spotting one slot that is itself drifting. * **Avoid for** — a plain time series (Sparkline) or one composition (SegmentedBar). `period` outside 4–12 warns in development: below that there is no cycle to see, above it the slots stop being separable. ## Variants [#variants] ```tsx <CyclePlot data={[38, 40, 45, 48, 52, 61, 44, 38, 42, 45, 48, 52, 61, 44, 38, 44, 45, 48, 52, 61, 44]} period={7} trend={false} />`" > <span className="inline-flex gap-4 items-center"> <CyclePlot data="[38, 40, 45, 48, 52, 61, 44, 38, 42, 45, 48, 52, 61, 44, 38, 44, 45, 48, 52, 61, 44]" period="7" center="median" width="150" height="32" /> <CyclePlot data="[38, 40, 45, 48, 52, 61, 44, 38, 42, 45, 48, 52, 61, 44, 38, 44, 45, 48, 52, 61, 44]" period="7" trend="false" width="150" height="32" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <CyclePlot data="[null, 40, 45, 48, 52, 61, null, 42, 45, 48, 52, 61, null, 44, 45, 48, 52, 61]" period="6" title="One slot always missing" width="160" height="32" /> ``` ```tsx `" > <CyclePlot data="[38, 45, 52, 44, 40, 48, 61]" period="7" title="One cycle" width="160" height="32" /> ``` ```tsx `" > <CyclePlot data="[3800, 4000, 4500, 4800, 5200, 6100, 4400, 3800, 4200, 4500, 4800, 5200, 6100, 4400]" period="7" locale="de-DE" title="Localized visits" width="200" height="36" /> ``` A slot with no finite values in it draws no mean tick and no within-slot line; the spine connects the non-empty slots only, joining an empty slot's neighbours directly rather than dipping to a made-up center. A single cycle (one value per slot) draws the spine and dots as usual, but no within-slot polylines — a line needs at least two observations in a slot. ## Why this default [#why-this-default] A mean spine plus raw slot lines, because seasonality and drift are different questions asked of the same data — and answering both on one mark would blur them. The within-slot lines are never smoothed and never joined across a slot boundary: each slot's polyline begins and ends inside its own column, so a Monday trend can never bleed into Tuesday. The `center` choice is explicit — mean by default, median when a slot's distribution is skewed — and the interactive per-slot announcement names which one it used. ## Accessibility [#accessibility] The accessible name states the peak and dip slots and any leading drift — **"Peaks slot 6 (61), dips slot 1 (38); slot 2 rising across 3 cycles."** The interactive entry steps the slots (mean, cycle count, drift) with ←/→, and steps the individual observations within a slot with ↑/↓. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | A flat series, reshaped row-major into `period` slots. | | `period` (required) | `number` | Slots per cycle (4–12) — e.g. 7 for weekdays. | | `slots` | `string[]` | Slot names for summaries, e.g. weekday labels. | | `center` | `"mean" \| "median"` | Center statistic — median for skewed slot distributions. | | `trend` | `boolean` | Within-slot micro-trend line (default true); false = spine + ticks only. | | `spine` | `boolean` | The slot-center spine (default true); false leaves within-slot drift only. | | `cycleUnit` | `string` | Cycle noun for the summary, e.g. 'weeks' (default 'cycles'). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # DataDiff (/docs/charts/data-diff) DataDiff answers "what changed between these two versions?". Each key gets a diverging bar: **removed leftward, added rightward, both always drawn** on one symmetric shared scale. Net is a mark you can turn on, never a replacement for the two bars — a +500/−480 churn and a +20/−0 trickle must never look alike. ```tsx <DataDiff data="[ { key: "users", added: 340, removed: 120 }, { key: "orders", added: 88, removed: 30 }, { key: "items", added: 40, removed: 20 }, { key: "tags", added: 24, removed: 8 }, { key: "notes", added: 12, removed: 6 }, { key: "flags", added: 8, removed: 3 }, ]" title="Schema diff" width="200" height="72" /> ``` ## Install [#install] ```tsx import { DataDiff } from "@microcharts/react/data-diff"; <DataDiff data={diff} title="Schema diff" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a table cell per dataset version, a KPI card for a sync or import job, any per-key added/removed audit where churn matters. * **Avoid for** — a plain ranking (MiniBar) or parts of a single whole (SegmentedBar). ## Variants [#variants] ```tsx <DataDiff data={[ { key: "users", added: 340, removed: 120 }, { key: "orders", added: 88, removed: 30 }, { key: "items", added: 40, removed: 20 }, ]} net label="totals" />`" > <span className="inline-flex gap-4"> <DataDiff data="[ { key: "users", added: 340, removed: 120 }, { key: "orders", added: 88, removed: 30 }, { key: "items", added: 40, removed: 20 }, ]" width="150" height="56" /> <DataDiff data="[ { key: "users", added: 340, removed: 120 }, { key: "orders", added: 88, removed: 30 }, { key: "items", added: 40, removed: 20 }, ]" label="totals" width="150" height="56" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <DataDiff data="[]" title="No keys" width="100" height="24" /> ``` ```tsx `"> <DataDiff data="[ { key: "a", added: 0, removed: 0 }, { key: "b", added: 0, removed: 0 }, ]" title="No changes" width="100" height="24" /> ``` An empty `data` array renders an empty chart and reports **"No data."** A non-empty diff where every key is 0/0 still draws its hairline placeholder ticks and reports **"No changes across 2 keys."** — the keys are named even when nothing about them changed. ## Why this default [#why-this-default] Both directions are always drawn, because net-only diffs hide churn: a table that added 500 rows and dropped 480 is not the same event as one that added 20 and dropped nothing, even though both net to roughly the same number. One symmetric scale spans every row so a big change never shrinks to fit a small one, and a key with no change still gets a hairline tick — the absence of a change is not the absence of the key. Cross-chart comparison goes through a shared `domain`. ## Accessibility [#accessibility] The accessible name states the totals, the key count, and the single largest change — **"+468 added, −170 removed across 3 keys; largest change: users (+220)."** The interactive entry steps the rows and announces each key's added, removed, and net change. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ key; added; removed }[]` | Per-key change counts — added and removed are non-negative magnitudes. | | `labels` | `boolean` | In-chart key tags for standalone use (host tables carry keys by default). | | `net` | `boolean` | A tick at added−removed per row — a summary mark, never the two bars. | | `order` | `"data" \| "net" \| "magnitude"` | Default 'data' keeps input order (schema order is often meaningful). | | `label` | `"totals" \| "none"` | 'totals' prints a +added / −removed footer. | | `maxItems` | `number` | Row cap (default 12); rows beyond it are dropped with a dev warning. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Delta (/docs/charts/delta) Delta is a text-first metric: a signed number with a direction glyph. It reads inline, next to a KPI, or inside a table cell. Direction is always doubled — a triangle *and* a color — so it never relies on color alone. ```tsx <span className="text-lg"> <Delta value="0.124" title="Revenue vs last week" /> </span> ``` ## Install [#install] ```tsx import { Delta } from "@microcharts/react/delta"; <Delta value={0.124} title="Revenue vs last week" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a KPI's change, period-over-period percent, inline metric movement. * **Avoid for** — showing a series or comparing magnitudes across items. ## Sizing [#sizing] Delta is text, not a fixed box — it takes the `font-size` of whatever wraps it and its glyph scales in `em`. Size it by the surrounding type: inline, it inherits the sentence; beside a KPI figure, lift the font-size to match. ## Variants [#variants] `from` derives a percent change; `positive="down"` flips only the color for metrics where down is good (latency, churn, cost). ```tsx `"> <span className="text-lg"> <Delta value="0.124" title="Percent" /> </span> ``` ```tsx `"> <span className="text-lg"> <Delta value="128" from="100" title="From prior" /> </span> ``` ```tsx `"> <span className="text-lg"> <Delta value="-0.08" title="Down is bad" /> </span> ``` ```tsx `"> <span className="text-lg"> <Delta value="-0.05" positive="down" title="Down is good" /> </span> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, the magnitude follows that locale's own grouping and decimal marks (a German reader sees a comma decimal and a space before the `%`, not a period). The leading sign is the library's own `+` / `−`, so it reads the same in every locale. ```tsx `"> <span className="text-lg"> <Delta value="0.124" format="{ style: "percent", maximumFractionDigits: 1 }" locale="de-DE" title="Localized change" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <span className="text-lg"> <Delta value="0" title="Flat" /> </span> ``` ```tsx <Delta value={Infinity} />`" > <span className="inline-flex gap-4 text-lg"> <Delta value="Number.NaN" title="Not a number" /> <Delta value="Number.POSITIVE_INFINITY" title="Infinite" /> </span> ``` A zero delta shows the flat glyph and **"No change."** — never a `+0%`/`−0%` that implies a direction with nothing behind it. `NaN` and `±Infinity` degrade the same way: the flat glyph, an em dash instead of a number, and **"No change."** rather than a misleading `NaN%`. ## Why this default [#why-this-default] Direction is always double-encoded — the triangle's shape carries it as much as the color does — because a red/green-only read fails for color-blind viewers and under `forced-colors`. `positive` flips only which color means "good"; it never changes which way the glyph points, so a metric where down is good (latency, churn, cost) still shows an honest down-pointing triangle, just in the "good" color. Percent is the default format because most deltas are relative change, not raw magnitude — pass `format` for currency, counts, or any other unit. Non-finite input renders as an em dash rather than `NaN%`, because a broken number should read as "nothing to report," not as a fabricated value. ## Accessibility [#accessibility] Delta renders accessible inline text — the glyph is decorative and the value carries the meaning. Color is a redundant channel on top of the direction glyph and the sign, so the change survives forced-colors and color-blind viewing. The interactive entry re-announces the figure through a polite live region when the value changes. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The change, or current value when from is set. | | `from` | `number` | Prior value; Delta shows the percent change. | | `positive` | `"up" \| "down"` | Which direction is good (colors only). | | `format` | `Intl.NumberFormatOptions \| fn` | Number formatting. | | `locale` | `string \| string[]` | BCP 47 locale(s) for the formatted number. | | `summary` | `string \| false` | Override or disable the auto summary. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # DepthWedge (/docs/charts/depth-wedge) DepthWedge answers "how much pressure is stacked on each side of the current level, and how wide is the gap between them?". Demand accumulates leftward from the spread and supply rightward, so the two filled wedges show the book's posture in a glyph. The y-scale is linear, full stop — log-depth reading belongs to full-size tools. ```tsx `" > <DepthWedge data="{ demand: [ { level: 99.75, amount: 420 }, { level: 99.5, amount: 360 }, { level: 99.25, amount: 280 }, { level: 99, amount: 200 }, { level: 98.5, amount: 120 }, ], supply: [ { level: 100.25, amount: 300 }, { level: 100.5, amount: 240 }, { level: 100.75, amount: 160 }, { level: 101, amount: 90 }, ], }" title="Order book" width="300" height="30" /> ``` ## Install [#install] ```tsx import { DepthWedge } from "@microcharts/react/depth-wedge"; <DepthWedge data={{ demand, supply }} title="Order book" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — order-book depth / liquidity, supply vs demand posture. * **Avoid for** — a time series (Sparkline) or a single ratio (Delta). ## Variants [#variants] ```tsx `" > <DepthWedge data="{ demand: [ { level: 99.5, amount: 420 }, { level: 99, amount: 260 }, ], supply: [ { level: 100.5, amount: 300 }, { level: 101, amount: 180 }, ], }" title="Normalized" width="300" height="30" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <DepthWedge data="{ demand: [ { level: 99.5, amount: 200 }, { level: 99, amount: 100 }, ], supply: [ { level: 100.5, amount: 200 }, { level: 101, amount: 100 }, ], }" title="Balanced" width="300" height="30" /> ``` ```tsx `" > <DepthWedge data="{ demand: [{ level: 99.5, amount: 200 }], supply: [] }" title="One-sided" width="300" height="30" /> ``` ## Why this default [#why-this-default] Linear scale plus a stated `levels` span because a wedge you can't interrogate must not editorialize — a silent log axis would exaggerate near-spread depth and flatter thin books. The visible range is part of the claim, so whenever the summary names a leading side it scopes the ratio with "within the shown range", and the spread — the gap between the best bid and best ask — is the headline number above the mid line. ## Accessibility [#accessibility] The accessible name states the posture, range-scoped — **"Demand outweighs supply 1.42× within the shown range; spread 1."** (the hero demo's order book). The interactive entry walks the levels with ←/→, announcing the cumulative depth on each side and its distance from the mid. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ demand, supply }` | Level/amount rows per side. | | `levels` | `number` | ± level distance from mid to include. | | `normalize` | `boolean` | Plot cumulative shares per side. | | `label` | `"spread" \| "none"` | The gap is the headline number. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # DicePips (/docs/charts/dice-pips) DicePips answers "what is this small count or severity?" the way dice do — a face you read without counting. The brain subitizes the canonical 1–6 patterns instantly. Zero is an empty face (zero, not missing); above six there is no subitizable pattern, so the face shows the exact numeral rather than inventing a seven-pip layout. The face never pretends. ```tsx <span className="inline-flex gap-3 items-center"> <DicePips value="1" size="20" title="one" /> <DicePips value="2" size="20" title="two" /> <DicePips value="3" size="20" title="three" /> <DicePips value="4" size="20" title="four" /> <DicePips value="5" size="20" title="five" /> <DicePips value="6" size="20" title="six" /> </span> ``` ## Install [#install] ```tsx import { DicePips } from "@microcharts/react/dice-pips"; <DicePips value={4} title="Severity" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a severity or rating 0–6 in a cell, an at-a-glance small count in a sentence, or an incident-severity badge. * **Avoid for** — counts above six (TallyMarks), magnitudes (MiniBar), or proportions (Progress). ## Variants [#variants] ```tsx <DicePips value={9} />`" > <span className="inline-flex gap-4 items-center"> <DicePips value="5" face="false" size="22" /> <DicePips value="9" size="22" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <DicePips value="0" size="22" /> ``` ```tsx `"> <DicePips value="-2" size="22" /> ``` ```tsx `"> <DicePips value="3.6" size="22" /> ``` ## Why this default [#why-this-default] The face outline keeps a lone die legible on any surface, so it is on by default; `face={false}` drops it for repeated table columns where the header already frames the column. Six is the ceiling because pip patterns above six are not subitizable — asking the reader to count invented pips would be slower than reading a number, so the chart refuses and shows the numeral instead. That numeral fallback is the documented honesty rule, shown live at `value={9}`. ## Accessibility [#accessibility] The accessible name states the value against its range — **"4 out of 6."** — and drops the frame to just the exact number once past six (**"9."**). Zero reads "0 out of 6." (a real zero), and an invalid value reads "No data." The interactive entry pops the pips into place on change (a short scale-up with a per-pip stagger, skipped under `prefers-reduced-motion`) and announces the new face through a polite live region; the pips are one value, so there is no cursor to move. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | Integer 0–6 (rounded); above 6 shows a numeral. | | `face` | `boolean` | Draw the die outline (default true). | 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](/docs/quickstart#the-shared-grammar). # DotPlot (/docs/charts/dot-plot) DotPlot answers "how do a few named values compare on one scale?" with the minimum ink per comparison. Dots over bars when the scale doesn't start at zero — position lies less than truncated bar length. ```tsx `" > <DotPlot data="[ { label: "Ada", value: 96 }, { label: "Kim", value: 41 }, { label: "Sam", value: 88 }, ]" title="Review scores" width="180" height="66" /> ``` ## Install [#install] ```tsx import { DotPlot } from "@microcharts/react/dot-plot"; <DotPlot data={team} title="Review scores" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — KPI leaderboards, named comparisons in cards, rows where a truncated bar would lie. * **Avoid for** — more than 7 rows or time series (Sparkline). ## Variants [#variants] ```tsx `" > <DotPlot data="[ { label: "Ada", value: 96 }, { label: "Kim", value: 41 }, { label: "Sam", value: 88 }, ]" title="Magnitude read" width="180" height="66" /> ``` ```tsx `"> <DotPlot data="[ { label: "Ada", value: 96 }, { label: "Kim", value: 41 }, { label: "Sam", value: 88 }, ]" label="value" highlight="Ada" title="Leaderboard" width="180" height="66" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <DotPlot data="[]" title="No data" width="100" height="16" /> ``` ```tsx `"> <DotPlot data="[{ label: "Only", value: 42 }]" title="Single" width="100" height="16" /> ``` ```tsx `" > <DotPlot data="[ { label: "Ada", value: 96 }, { label: "Kim", value: null }, { label: "Sam", value: 88 }, ]" title="Gap preserved" width="180" height="66" /> ``` An empty series has nothing to compare, so no dots draw and the accessible name reads **"No data."** A single category still renders normally — one dot, one label — with the summary's "category"/"categories" wording matching the count (**"1 category. Highest Only 42, lowest Only 42."**). A `null` value draws no dot and no label for its row, but the row still occupies its slot in the vertical rhythm — the real values around it keep the same spacing they'd have in a fully populated set — and it's excluded from the category count in the summary, not counted as a comparison with nothing. ## Why this default [#why-this-default] Without `stem` the domain fits the data (a position read); with `stem` the domain is forced through zero (a magnitude read) — the prop flips the honesty regime, and the docs say so. Coincident dots on adjacent rows de-overlap by half a unit; labels truncate by character count and drop entirely when rows get too dense — all pure arithmetic, nothing measured. ## Accessibility [#accessibility] The accessible name carries count and extremes — **"3 categories. Highest Ada 96, lowest Kim 41."** The interactive entry roves rows and announces each with its rank (**"Ada: 96 — 1st of 3."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value }[]` | Named values. | | `stem` | `boolean` | Hairline from zero — flips to a magnitude read (zero-anchored domain forced). | | `highlight` | `number \| string` | Accent one category. | | `label` | `"value" \| "none"` | Value text beside each dot (drops out under 8-unit rows). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # DualSparkline (/docs/charts/dual-sparkline) DualSparkline answers "how is this series doing against its benchmark?" Exactly two series, ever — three overlapped lines at 16 px are unreadable (SparkGroup for that). The benchmark whispers: dashed, thinner, neutral — never distinguished by color alone. ```tsx <DualSparkline data="[12, 13, 12.4, 14, 15.2, 14.8, 16, 17.5, 17, 18.4, 19, 21]" compare="[12, 12.4, 12.8, 13.1, 13.6, 14, 14.2, 14.8, 15, 15.4, 15.8, 16]" title="Conversion vs market" width="220" height="28" /> ``` ## Install [#install] ```tsx import { DualSparkline } from "@microcharts/react/dual-sparkline"; <DualSparkline data={ours} compare={market} title="Conversion vs market" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — metric-vs-benchmark in table cells, actual-vs-plan in KPI cards. * **Avoid for** — 3+ series (SparkGroup), or different units per series (never dual axes). ## Variants [#variants] ```tsx <DualSparkline data={ours} compare={market} band={[13, 16]} />`" > <span className="inline-flex flex-col gap-3"> <DualSparkline data="[12, 13, 12.4, 14, 15.2, 14.8, 16, 17.5, 17, 18.4, 19, 21]" compare="[12, 12.4, 12.8, 13.1, 13.6, 14, 14.2, 14.8, 15, 15.4, 15.8, 16]" label="last" title="With last value" width="220" height="28" /> <DualSparkline data="[12, 13, 12.4, 14, 15.2, 14.8, 16, 17.5, 17, 18.4, 19, 21]" compare="[12, 12.4, 12.8, 13.1, 13.6, 14, 14.2, 14.8, 15, 15.4, 15.8, 16]" band="[13, 16]" title="With band" width="220" height="28" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <DualSparkline data="[12, 13, 12.4, 14, 15.2, 14.8, 16, 17.5]" compare="[12, 12.4, 12.8, 13.1]" title="Benchmark ends early" width="200" height="28" /> ``` ```tsx `"> <DualSparkline data="[12, null, 12.4, 14, null, 14.8, 16]" compare="[12, 12.4, null, 13.1, 13.6, null, 14.2]" title="Independent gaps" width="200" height="28" /> ``` ```tsx `" > <DualSparkline data="[1200, 1300, 1240, 1400, 1520, 1480, 1600]" compare="[1200, 1240, 1280, 1310, 1360, 1400, 1420]" label="last" locale="de-DE" title="Localized values" width="220" height="28" /> ``` Each series carries its own gaps independently — a `null` in `data` breaks only the primary line at that index, a `null` in `compare` only the benchmark, and the nearest-x hover still reports both values (or "no data" for whichever side is missing). With a `locale`, the endpoint label and both hover values follow that locale's grouping. ## Why this default [#why-this-default] One shared domain across both series — the entire point is comparability, so there are no dual axes and no per-series normalization. A shorter benchmark simply ends; stretching it would fake correlation. Coincident endpoints dedupe to one dot so ink never doubles. ## Accessibility [#accessibility] The accessible name reads both trends and both endpoints — **"Trending up 75% vs benchmark up 33%. Last 21 vs 16."** Identical series read "Matching benchmark." The interactive entry announces pairs (**"Point 9 of 12: 17 vs 15."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | The series being judged. | | `compare` (required) | `(number \| null)[]` | The benchmark — dashed, thinner, neutral. | | `curve` | `"linear" \| "smooth" \| "step"` | Line shape (default 'linear'). | | `band` | `[number, number]` | Normal-range band behind both (shared grammar). | | `label` | `"last" \| "none"` | Endpoint value label for the primary series. | | `dots` | `"auto" \| "none"` | Endpoint dots on both lines (default "auto"). | | `seriesStrings` | `SeriesStrings` | i18n strings for the per-series trend clauses. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # DualWindowMeter (/docs/charts/dual-window-meter) DualWindowMeter answers "is the level compliant against its target both right now and on average — momentary spikes vs sustained drift?". From one raw series it computes two rolling means: a thin fast window that reacts instantly and a thick slow window that carries the sustained read, both against a target line. It is the general form of any noisy metric with a compliance target. ```tsx <DualWindowMeter data="Array.from({ length: 60 }, (_, i) => -22 + Math.sin(i / 3) * 4 + Math.sin(i / 11) * 2 - (i > 40 ? 2 : 0))" target="-23" title="Loudness" format="{ maximumFractionDigits: 1 }" width="300" height="28" /> ``` ## Install [#install] ```tsx import { DualWindowMeter } from "@microcharts/react/dual-window-meter"; <DualWindowMeter data={samples} target={-23} format={{ maximumFractionDigits: 1 }} title="Loudness" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — loudness / LUFS metering, latency SLO or CPU-headroom compliance. * **Avoid for** — a single series (Sparkline) or anything without a target to compare against. ## Variants [#variants] ```tsx -22 + Math.sin(i / 3) * 4 + Math.sin(i / 11) * 2, ); <DualWindowMeter data={samples} target={-23} band={[-25, -21]} />`" > <DualWindowMeter data="Array.from({ length: 60 }, (_, i) => -22 + Math.sin(i / 3) * 4 + Math.sin(i / 11) * 2)" target="-23" band="[-25, -21]" title="Corridor" width="300" height="28" /> ``` ```tsx -22 + Math.sin(i / 3) * 4 + Math.sin(i / 11) * 2, ); // both window sizes are part of the reading — state them, never hide them <DualWindowMeter data={samples} target={-23} windows={[5, 20]} />`" > <DualWindowMeter data="Array.from({ length: 60 }, (_, i) => -22 + Math.sin(i / 3) * 4 + Math.sin(i / 11) * 2)" target="-23" windows="[5, 20]" title="Custom windows" width="300" height="28" /> ``` ```tsx -22 + Math.sin(i / 3) * 4 + Math.sin(i / 11) * 2 - (i > 40 ? 2 : 0), ); <DualWindowMeter data={samples} target={-23} format={{ maximumFractionDigits: 1 }} locale="de-DE" />`" > <DualWindowMeter data="Array.from({ length: 60 }, (_, i) => -22 + Math.sin(i / 3) * 4 + Math.sin(i / 11) * 2 - (i > 40 ? 2 : 0))" target="-23" format="{ maximumFractionDigits: 1 }" locale="de-DE" title="Localized readings" width="300" height="28" /> ``` With a `locale`, the right-edge readings and the accessible summary follow that locale's decimal mark — the fast reading above renders "-23,9", not "-23.9", and the accessible name reads "Slow window -25 vs target -23; fast -23,9." ## Edge cases [#edge-cases] ```tsx `" > <DualWindowMeter data="[48, 48.3, 48.6, 48.9, 49.2, 49.5, 49.8, 50.1, 50.4, 50.7]" target="50" title="Filling" width="200" height="28" /> ``` ## Why this default [#why-this-default] Thin-fast, thick-slow because the sustained read should carry more ink — a momentary spike on the fast trace matters less than a slow-window drift away from target. The window sizes are part of the reading, not a hidden implementation detail — `windows` is an explicit prop, and the examples that change it state both sizes. Both traces always share one domain; a trace begins only where its window has filled, never faking a partial-window value. ## Accessibility [#accessibility] The accessible name leads with the sustained read — **"Slow window -25 vs target -23; fast -23,9."** The interactive entry roves the samples with ←/→, announcing the fast value, the slow value, and the target at each point. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Raw samples; two rolling means are computed. | | `target` (required) | `number` | The compliance line — required. | | `windows` | `[number, number]` | Fast/slow integration windows (samples). | | `band` | `[number, number]` | A compliance corridor instead of one line. | | `domain` | `[number, number]` | Fix the vertical scale instead of auto-fitting both traces. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Dumbbell (/docs/charts/dumbbell) Dumbbell answers "where did each row start and end?". The hollow dot is *before*, the filled dot is *after* — direction is shape-coded, so it never relies on color alone. With `positive` the connector takes the valence token by direction. ```tsx <Dumbbell data="[{ from: 62000, to: 84000 }]" title="Band move" style="{ width: 200, height: 28 }" /> ``` ## Install [#install] ```tsx import { Dumbbell } from "@microcharts/react/dumbbell"; <Dumbbell data={[{ from: 62000, to: 84000 }]} title="Band move" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — salary bands, before/after per table row, ranges. * **Avoid for** — many categories where crossings matter (Slope) or the path between (Sparkline). ## Variants [#variants] ```tsx `" > <Dumbbell data="[ { label: "Paris", from: 52, to: 61 }, { label: "Oslo", from: 66, to: 60 }, ]" positive="up" title="Moves" style="{ width: 200, height: 44 }" /> ``` ```tsx `"> <Dumbbell data="[{ from: 40, to: 60 }]" label="value" domain="[0, 100]" title="With values" style="{ width: 240, height: 26 }" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <Dumbbell data="[{ from: 55, to: 55 }]" title="Flat" style="{ width: 200, height: 24 }" /> ``` When a row's `from` equals its `to`, the connector is dropped and only one filled dot is drawn — never a hollow-and-filled pair sitting on top of each other pretending to be two points. The summary says **"No change at 55."** for a single row. ## Why this default [#why-this-default] Hollow → filled reads as before → after without a legend, and renders identically whichever way the data runs — direction comes from the values, not the array order. For *ranges* (min→max, confidence spans) the docs require dropping `positive`: a range has no valence, and coloring it green or red would invent one. ## Accessibility [#accessibility] Single row: **"From 40 to 60, up 50%."**; a degenerate pair says **"No change at 55."**; multi-row leads with the largest change (**"2 rows. Largest change Paris, up 17%."**). The interactive entry roves rows with ↑/↓ (←/→ do the same), announcing each row's own pair — **"From 52 to 61, up 17%."** The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label?; from; to }[]` | Start/end pairs. | | `positive` | `"up" \| "down"` | Direction valence for CHANGES; drop it for ranges (no valence). | | `label` | `"value" \| "none"` | From/to values outside the dots (drop when the span is tight). | | `highlight` | `number \| string` | Accent one row. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # EnsembleGhosts (/docs/charts/ensemble-ghosts) EnsembleGhosts answers "what could happen, across the simulated futures?". It draws a faint bundle of member paths with one emphasized representative — because a mean line hides that futures disagree in **shape**, not just endpoint. Ghost selection is fully deterministic (evenly spaced endpoint-rank quantiles), so the same input renders identically every time. ```tsx `" > <EnsembleGhosts data="[[40, 41, 43, 45, 47, 50], [40, 39, 38, 36, 35, 33], [40, 42, 44, 47, 49, 52], [40, 40, 41, 41, 42, 43], [40, 43, 47, 52, 56, 61], [40, 38, 35, 32, 30, 28], [40, 41, 42, 44, 45, 46], [40, 39, 40, 41, 42, 44]]" title="Simulated futures" width="200" height="44" /> ``` ## Install [#install] ```tsx import { EnsembleGhosts } from "@microcharts/react/ensemble-ghosts"; <EnsembleGhosts data={futures} title="Simulated futures" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a KPI card that shows the futures, not the average; Monte-Carlo / simulation output where paths disagree in shape; showing that outcomes fan out. * **Avoid for** — interval precision (ForecastCone) or a single path (Sparkline). ## Variants [#variants] ```tsx <EnsembleGhosts data={[ [40, 41, 43, 45, 47, 50], [40, 39, 38, 36, 35, 33], [40, 42, 44, 47, 49, 52], [40, 43, 47, 52, 56, 61], [40, 38, 35, 32, 30, 28], ]} emphasis="median" />`" > <span className="inline-flex gap-4 items-center"> <EnsembleGhosts data="[ [40, 41, 43, 45, 47, 50], [40, 39, 38, 36, 35, 33], [40, 42, 44, 47, 49, 52], [40, 43, 47, 52, 56, 61], [40, 38, 35, 32, 30, 28], ]" width="150" height="40" /> <EnsembleGhosts data="[ [40, 41, 43, 45, 47, 50], [40, 39, 38, 36, 35, 33], [40, 42, 44, 47, 49, 52], [40, 43, 47, 52, 56, 61], [40, 38, 35, 32, 30, 28], ]" emphasis="median" width="150" height="40" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <EnsembleGhosts data="[[40, 43, 47, 52, 56, 61]]" title="One simulated path" width="160" height="40" /> ``` ```tsx `" > <EnsembleGhosts data="[ [4000, 4100, 4300, 4500, 4700, 5000], [4000, 3900, 3800, 3600, 3500, 3300], [4000, 4200, 4400, 4700, 4900, 5200], ]" locale="de-DE" title="Localized endpoints" width="160" height="40" /> ``` With one member, there is no bundle to show — the chart draws that single path as the representative, and the summary states its ending value rather than a spread. A member that contains a non-finite value (`NaN`, `Infinity`) is excluded entirely from ghost selection and the median, not gapped mid-path — a dev-only console warning flags it, since a partially invalid future usually means bad simulation output. ## Why this default [#why-this-default] A few faint paths and one emphasized, because a mean line hides that futures disagree in shape, not just endpoint — two ensembles can share an average and a final range while telling completely different stories along the way. The emphasized path defaults to the **real member** closest to the pointwise median, so the representative is an outcome that actually happened in the simulation, not a synthetic average of paths that never occurred (`emphasis="median"` draws that synthetic path instead). Selection and emphasis are deterministic — nothing about this chart varies between renders of the same data. `label="end"` (default) states the emphasized path's landing value in a right gutter; pass `label="none"` to drop it. The static frame is not a hypothetical-outcome plot. The **loop** — flipping through the members one at a time on hover — is the HOP, and it lives only in the interactive entry, gated on reduced motion with arrow-key stepping as the non-animated equivalent. ## Accessibility [#accessibility] The accessible name states the endpoint spread and the typical path — **"5 simulated paths end between 28 and 61; typical path ends near 50."** The interactive entry flips through the members (the HOP loop) on hover; with reduced motion, ←/→ step them discretely, and each member is announced with its endpoint. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[][]` | Ensemble members — 2–50 simulated paths. | | `ghosts` | `number` | Rendered member count (deterministic endpoint-rank selection). Default 8, cap 12. | | `emphasis` | `"nearest-median" \| "median" \| number` | A real median-like member, the synthetic median, or a pinned member. | | `endpoints` | `boolean` | Ghost endpoint dots — makes the final-value spread countable. | | `label` | `"end" \| "none"` | Emphasised path endpoint in a right gutter (default end). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # ErrorBudget (/docs/charts/error-budget) ErrorBudget answers "are we burning the error budget too fast to survive the window?". The budget remaining rides against the **steady-burn diagonal** — the pace that exactly spends the window — so "too fast" is legible at a glance: below the diagonal means you're outrunning your budget. Faster burn-rate reference lines (the Google-SRE 1×/6×/14.4× **convention**, not physics) sit below it as faint policy context. ```tsx <ErrorBudget data="[1, 0.96, 0.93, 0.9, 0.86, 0.83, 0.79, 0.75, 0.71, 0.67, 0.64, 0.62]" window="30" unit="day" label="remaining" title="Checkout SLO" width="260" height="30" /> ``` ## Install [#install] ```tsx import { ErrorBudget } from "@microcharts/react/error-budget"; <ErrorBudget data={remaining} window={30} title="Checkout SLO" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — an SLO error budget in a KPI card, a service list where each row is a budget, spotting a fast-burn before it exhausts the window. * **Avoid for** — a plain uptime series (Sparkline) or a one-number budget (Progress). ## Variants [#variants] ```tsx <ErrorBudget data={remaining} window={30} rates={[1]} />`" > <span className="inline-flex flex-col gap-1.5"> <ErrorBudget data="[1, 0.82, 0.6, 0.38, 0.18, 0.04, 0]" window="20" unit="day" title="Fast-burn" width="220" height="28" /> <ErrorBudget data="[1, 0.96, 0.93, 0.9, 0.86, 0.83, 0.79, 0.75, 0.71, 0.67, 0.64, 0.62]" window="30" rates="[1]" unit="day" title="Diagonal only" width="220" height="28" /> </span> ``` ```tsx `"> <ErrorBudget data="[1, 0.96, 0.93, 0.9, 0.86, 0.83, 0.79, 0.75, 0.71, 0.67, 0.64, 0.62]" window="30" unit="day" locale="de-DE" title="Localized" width="220" height="28" /> ``` `format` defaults to a percent formatter; with `locale` it follows that locale's own conventions for the remaining-budget label — "62 %" (space before the sign) under `de-DE` rather than the English "62%". ## Edge cases [#edge-cases] ```tsx `"> <ErrorBudget data="[]" title="No data yet" width="220" height="28" /> ``` ```tsx `"> <ErrorBudget data="[0.9]" window="30" unit="day" title="Day 1" width="220" height="28" /> ``` ```tsx `"> <ErrorBudget data="[1, 0.82, 0.6, 0.38, 0.18, 0.04, 0]" window="20" unit="day" title="Exhausted" width="220" height="28" /> ``` With no data the chart renders an empty root and the accessible name says **"No data."**; a single point still draws the diagonal, wedges, and endpoint, though `currentRate` (which needs a prior step) reads `0`. Once the remaining line reaches zero, an ✕ at that first zero-crossing replaces the endpoint dot, and the summary reads **"Budget exhausted at day 7 of 20."** instead of the normal remaining/rate sentence. Values are clamped to `0–1`, so nothing is ever drawn below the floor or above a full budget. ## Why this default [#why-this-default] Remaining-vs-diagonal, because "too fast" is only legible against the pace that exactly spends the window. The 1×/6×/14.4× reference lines are the SRE Workbook's multiwindow burn-rate alert **convention** — a policy default, never universal law — so `rates` is configurable and the lines render as faint background context, never data-colored. `currentRate` is the observed burn slope over the last `max(2, ⌈n/6⌉)` steps ÷ the steady slope; when the budget hits zero, an ✕ marks the crossing and the summary says so. ## Accessibility [#accessibility] The accessible name states the budget, the elapsed window, and the burn rate — **"62% of error budget remains at day 12 of 30 — burning at 0.6× the steady rate."**; an exhausted window reads "Budget exhausted at day N of M." The interactive entry steps the days and announces each step's remaining and local burn rate. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Budget remaining (0–1) per elapsed step; index 0 is 1.0. | | `window` | `number` | Total steps in the SLO window (default = data.length). | | `rates` | `number[]` | Burn-rate reference multiples (default the SRE 1×/6×/14.4× convention). | | `unit` | `string` | Period noun for the summary (default "day"). | | `label` | `"remaining" \| "none"` | Current budget % in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # EtaBar (/docs/charts/eta-bar) EtaBar answers "how long is this actually going to take, given how it has actually been going?". Its x-axis is time, not fraction: the solid part is the elapsed share of the predicted total, and the muted remainder is sized by the observed rate. When the rate drops, the remainder honestly grows — the download bar, told truthfully. ```tsx <EtaBar progress="0.64" elapsed="3.6" rate="0.18" etaFormat="(t) => `${Math.round(t)} min`" title="Export" width="280" height="16" /> ``` ## Install [#install] ```tsx import { EtaBar } from "@microcharts/react/eta-bar"; <EtaBar progress={0.64} elapsed={3.6} rate={0.18} etaFormat={(t) => `${Math.round(t)} min`} title="Export" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — download / export progress, job-queue ETAs, deploy timers. * **Avoid for** — fraction-only progress (Progress) or unbounded counters (Delta). ## Motion, and reduced motion [#motion-and-reduced-motion] The interactive entry eases the elapsed/remainder split (SVG `x`/`width`) to its new geometry whenever `progress`, `elapsed`, or `rate` change — the split only ever moves to a value computed from data you passed in on that render; it never interpolates ahead of an as-yet-unseen future frame. The transition lives in shared CSS (`.mc-eta-live rect`), so it inherits the shared `:where(.mc-root *) { transition: none }` reduced-motion block: with `prefers-reduced-motion: reduce` the bar snaps straight to each new split instead of easing. The live region re-announces the forecast on a throttle (`announceEvery`, default 10 s) so a fast-updating value doesn't spam a screen reader. ## Variants [#variants] ```tsx `"> <EtaBar progress="0.42" elapsed="10" rate="0.05" label="percent" title="Percent" width="280" height="16" /> ``` ```tsx `" > <EtaBar progress="0.42" elapsed="10" rate="0.05" locale="de-DE" title="Localized ETA" width="280" height="16" /> ``` Without an `etaFormat`, the remaining-time figure falls back to `format`/`locale` — under `de-DE` that's a decimal comma ("11,6") rather than the English decimal point ("11.6"). Pass `etaFormat` (as the hero example does) to add a unit; it always receives the raw number, so it can format the unit itself in whatever locale-aware way the caller needs. ## Edge cases [#edge-cases] ```tsx `"> <EtaBar progress="0.3" elapsed="40" rate="0" title="Stalled transfer" width="280" height="16" /> ``` ```tsx `" > <EtaBar progress="0.08" elapsed="30" rate="0.001" title="Barely started" width="280" height="16" /> ``` ```tsx `"> <EtaBar progress="1" elapsed="12" rate="0.1" title="Complete" width="280" height="16" /> ``` An explicit `rate` of `0`, or an absent `rate` from which no positive average can be derived from `elapsed`, renders the remainder as a diagonal-hatched texture instead of a solid bar — "unknown," not a hidden guess — and the summary says **"stalled"** rather than naming a duration. When the predicted remainder is far larger than the elapsed time, the done segment would round to an unreadable sliver, so the geometry clamps it to a visible 10% and adds a chevron marking the clamp as approximate. At `progress >= 1` the bar fills completely regardless of `rate`. ## Why this default [#why-this-default] The ETA label is the default because "how long?" is the question a plain progress bar pretends to answer. The remainder is sized by the observed rate, never linear interpolation — so a stalling transfer looks stalled instead of marching to a fake finish. When the rate is unknown or zero the remainder becomes an indeterminate texture and the summary says so, rather than inventing a countdown. ## Accessibility [#accessibility] The accessible name is the honest forecast — **"42% done; about 11.6 remaining at the current rate."** A stalled transfer reads **"30% done; stalled."** and a finished one **"Done."** The interactive entry re-announces on a throttle as the forecast changes. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `progress` (required) | `number` | Completed fraction 0–1. | | `elapsed` (required) | `number` | Time spent, any unit. | | `rate` | `number` | Progress per time unit — pass a recent-window rate. | | `label` | `"eta" \| "percent" \| "none"` | The remaining-time read is the product. | | `etaFormat` | `(t: number) => string` | Unit-bearing ETA label ("2 min") — the caller owns units. | | `announceEvery` | `number` | (interactive) Minimum ms between live-region announcements as the ETA streams (default 10000). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # EventRaster (/docs/charts/event-raster) EventRaster answers "when did each source fire — and do sources fire together, in sequence, or not at all?". Vertical bands reveal synchronization, diagonals reveal propagation, and sparse rows reveal silence. One tick is always one event — the only exception is the disclosed `overflow="bin"` mode for aliasing lanes. ```tsx <EventRaster data="[ { label: "api", events: [2, 5, 6, 14, 20, 21, 33, 40, 41, 48, 55] }, { label: "db", events: [3, 6, 15, 21, 34, 41, 55] }, { label: "cache", events: [6, 21, 41, 55] }, { label: "queue", events: [10, 30, 50] }, ]" title="Service events" width="300" height="56" /> ``` ## Install [#install] ```tsx import { EventRaster } from "@microcharts/react/event-raster"; <EventRaster data={services} title="Service events" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — service events across sources, agent steps, cron / sensor triggers. * **Avoid for** — a single lane (RugStrip) or continuous rates (Sparkline). ## Variants [#variants] ```tsx `"> <EventRaster data="[ { label: "api", events: [2, 5, 6, 14, 20, 21, 33, 40, 41, 48, 55] }, { label: "db", events: [3, 6, 15, 21, 34, 41, 55] }, { label: "cache", events: [6, 21, 41, 55] }, ]" emphasis="api" title="api emphasised" width="280" height="56" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <EventRaster data="[ { label: "api", events: [2, 5, 6, 14, 20, 33, 40, 48] }, { label: "db", events: [] }, ]" title="One quiet lane" width="220" height="32" /> ``` ```tsx i * 0.3) }]} overflow="bin" />`" > <EventRaster data="[{ label: "requests", events: Array.from({ length: 200 }, (_, i) => i * 0.3) }]" overflow="bin" title="High-rate lane" width="220" height="20" /> ``` ```tsx `"> <EventRaster data="[{ label: "boot", events: [0] }]" title="Single event" width="160" height="16" /> ``` ## Why this default [#why-this-default] Lanes stay aligned to a shared time domain because vertical banding — several sources firing at the same instant — is the phenomenon the chart exists to reveal. An empty lane is kept, not dropped: silence is signal. When a lane is so dense that ticks would alias into a solid smear, it switches to per-bucket counts shown as opacity, and the summary says which lanes were binned — the encoding change never hides. That is `overflow="bin"`, the default; `overflow="clip"` opts out and keeps one tick per event whatever the density. ## Accessibility [#accessibility] The accessible name summarises the field — **"3 lanes, 22 events; busiest api (11)."** The interactive entry roves lanes with ↑/↓ and events with ←/→, announcing each event's lane, time, and position within the lane. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label, events }[]` | One lane per source. | | `emphasis` | `string` | Accents one lane — the sync read. | | `labels` | `boolean` | Left-gutter lane names (on ≤ 8 lanes). | | `overflow` | `"bin" \| "clip"` | Aliasing lanes bin to counts (disclosed). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # EventTimeline (/docs/charts/event-timeline) EventTimeline answers "what happened when, and for how long?" — uptime windows, on-call shifts, release spans and incident points on one row. Diamonds mark instants, rects mark durations: the type distinction is a shape, so it survives 12 px where color coding wouldn't. ```tsx `" > <EventTimeline data="[ { start: Date.UTC(2026, 5, 3, 1), end: Date.UTC(2026, 5, 3, 5), label: "Freeze", kind: "accent" }, { start: Date.UTC(2026, 5, 3, 6), end: Date.UTC(2026, 5, 3, 15), label: "Healthy", kind: "positive" }, { start: Date.UTC(2026, 5, 3, 11), label: "Incident", kind: "negative" }, { start: Date.UTC(2026, 5, 3, 16), end: Date.UTC(2026, 5, 3, 18), kind: "negative" }, { start: Date.UTC(2026, 5, 3, 20), label: "Release" }, ]" domain="[Date.UTC(2026, 5, 3), Date.UTC(2026, 5, 4)]" title="API uptime" width="240" height="30" /> ``` ## Install [#install] ```tsx import { EventTimeline } from "@microcharts/react/event-timeline"; <EventTimeline data={windows} domain={today} title="API uptime" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — per-service uptime rows, on-call shifts and release windows in cards. * **Avoid for** — more than \~12 items, or aggregated durations (MiniBar of totals). ## Variants [#variants] ```tsx `" > <EventTimeline data="[ { start: Date.UTC(2026, 5, 3, 6), end: Date.UTC(2026, 5, 3, 15), label: "Healthy", kind: "positive", }, { start: Date.UTC(2026, 5, 3, 11), label: "Incident", kind: "negative" }, ]" domain="[Date.UTC(2026, 5, 3), Date.UTC(2026, 5, 4)]" now="Date.UTC(2026, 5, 3, 21)" title="With now" width="240" height="30" /> ``` ```tsx `" > <EventTimeline data="[ { start: Date.UTC(2026, 5, 3, 6), end: Date.UTC(2026, 5, 3, 15), label: "Healthy", kind: "positive", }, { start: Date.UTC(2026, 5, 3, 16), end: Date.UTC(2026, 5, 3, 18), label: "Deploy", kind: "accent", }, ]" domain="[Date.UTC(2026, 5, 3), Date.UTC(2026, 5, 4)]" label="spans" width="280" height="26" title="Labeled spans" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <EventTimeline data="[ { start: Date.UTC(2026, 5, 3, 9), label: "Deploy" }, { start: Date.UTC(2026, 5, 3, 14), label: "Alert", kind: "negative" }, { start: Date.UTC(2026, 5, 3, 18), label: "Resolved", kind: "positive" }, ]" domain="[Date.UTC(2026, 5, 3), Date.UTC(2026, 5, 4)]" title="Today's events" width="220" height="16" /> ``` ```tsx `" > <EventTimeline data="[{ start: Date.UTC(2026, 5, 2, 20), end: Date.UTC(2026, 5, 3, 10), label: "Maintenance" }]" domain="[Date.UTC(2026, 5, 3), Date.UTC(2026, 5, 3, 6)]" title="Clipped window" width="220" height="16" /> ``` ## Why this default [#why-this-default] Duration is length on a linear time axis — never log or compressed time. Items that overlap the window edge are clipped flat (honest partial visibility); fully-outside items are excluded with a dev warning. Overlapping spans render translucent in data order — a legibility device, not an encoding; the exact intervals live in the announcements. ## Accessibility [#accessibility] The accessible name is the coverage read — **"2 spans covering 46% of the window; 0 events."** — where coverage merges intervals first, so overlaps never double-count. The interactive entry cycles items chronologically: spans announce **"Freeze: Jun 3, 01:00 to Jun 3, 05:00 — 4h."**, instants **"Incident: Jun 3, 11:00."** The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ start; end?; label?; kind? }[]` | Spans (with end) and point events (without), ms epoch or Date. | | `domain` | `[start, end]` | The window — fix it across rows for small multiples. | | `now` | `number \| Date` | Current-moment tick; authored, never implicit. | | `label` | `"none" \| "spans"` | Centered in-span labels with deterministic drop-out. | | `dateFormat` | `Intl.DateTimeFormatOptions \| (d: Date) => string` | (interactive) Announced timestamp format for focused events (defaults to a locale date-time). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # FatDigits (/docs/charts/fat-digits) FatDigits answers "which numbers in this dense column are big, before I read them?" The numeral is always the exact value; font *weight* is a second, redundant channel — five (or three) ordinal tiers mapped from your `domain` — so the large numbers pop preattentively as you scan a column. Weight is never the primary read: it is ordinal and coarse, and the number is right there. ```tsx <span style="{ display: "inline-flex", flexDirection: "column", alignItems: "flex-end", gap: 2 }" className="tabular-nums"> <FatDigits value="1204" domain="[0, 2100]" summary="false" fontSize="16" /> <FatDigits value="318" domain="[0, 2100]" summary="false" fontSize="16" /> <FatDigits value="2100" domain="[0, 2100]" summary="false" fontSize="16" /> <FatDigits value="76" domain="[0, 2100]" summary="false" fontSize="16" /> </span> ``` ## Install [#install] ```tsx import { FatDigits } from "@microcharts/react/fat-digits"; <FatDigits value={1204} domain={[0, 2100]} title="Revenue" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a dense numeric table column you scan for the big ones, a KPI number that should carry its own magnitude, or an amount in a sentence. * **Avoid for** — trends (Sparkline), proportions (Progress), or comparisons (MiniBar). ## Variants [#variants] ```tsx <FatDigits value={1204} domain={[0, 2100]} tiers={3} />`" > <span className="inline-flex gap-5 items-center"> <FatDigits value="1902" encode="digit" fontSize="18" /> <FatDigits value="1204" domain="[0, 2100]" tiers="3" fontSize="18" /> </span> ``` `format` also takes `Intl.NumberFormatOptions` — the numeral itself follows the locale's own grouping and decimal marks. ```tsx `" > <FatDigits value="12040" domain="[0, 20000]" format="{ style: "currency", currency: "EUR", maximumFractionDigits: 0 }" locale="de-DE" fontSize="18" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <FatDigits value="1204" fontSize="18" /> ``` ```tsx `"> <FatDigits value="Number.NaN" domain="[0, 2100]" fontSize="18" title="Missing" /> ``` A non-finite value renders nothing (no numeral, no weight) and reports **"No data."** rather than guessing a tier. ## Why this default [#why-this-default] Value mode with five tiers is the default because scanning a column is the use case, and five is the most weight steps that stay discriminable at text size. Always pass a `domain` — without one a lone number has no tier to sit in, so it renders at the middle weight and means nothing. `encode="digit"` instead weights each digit by its own magnitude, a redundancy that helps scan long ids and amounts. This is adapted from the FatFonts idea: the research encodes magnitude as glyph ink area with a custom font; shipping a font would add a dependency, so weight tiers on the inherited font carry the ordinal instead — the numeral is always the exact value. On a font without many weights the browser snaps to the nearest available face, so fewer of the tiers stay visually distinct. ## Accessibility [#accessibility] The accessible name is the exact value and its tier — **"1,204 — tier 3 of 5."** — and in digit mode just the number, since each digit carries its own weight. The interactive entry eases the weight to its new tier on variable fonts (it snaps otherwise) with no layout shift, and announces the value and tier through a polite live region. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The number (always the exact value). | | `domain` | `readonly [number, number]` | Maps value to a weight tier — always pass one. | | `encode` | `"value" \| "digit"` | value weights the whole numeral; digit weights each digit by its own magnitude. | | `tiers` | `3 \| 5` | Weight steps (default 5). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # FillWord (/docs/charts/fill-word) FillWord answers "how far along is this named task?" by making the label *be* the bar. A muted word is overlaid with an accent copy of itself, clipped to the value fraction of the word's own inked extent — so 50% visually bisects the word. The fill is a percentage of the glyphs you see, never of a hidden wider track. It trades some precision for a read that needs no separate label. ```tsx <FillWord word="uploading" value="0.62" title="Upload" fontSize="18" /> ``` ## Install [#install] ```tsx import { FillWord } from "@microcharts/react/fill-word"; <FillWord word="uploading" value={0.62} /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a labelled progress read in a sentence or cell, a sync/upload status where the label names the task, or a quota/TTL where the word is the metric. * **Avoid for** — precise percentages (Progress), trends (Sparkline), or many parallel bars (MiniBar). ## Variants [#variants] ```tsx <FillWord word="storage" value={0.4} label="value" />`" > <span className="inline-flex gap-5 items-center"> <FillWord word="expiring" value="0.7" mode="drain" fontSize="16" /> <FillWord word="storage" value="0.4" label="value" fontSize="16" /> </span> ``` ## Edge cases [#edge-cases] ```tsx <FillWord word="uploading" value={1} />`" > <span className="inline-flex gap-5 items-center"> <FillWord word="uploading" value="0" fontSize="16" title="0%" /> <FillWord word="uploading" value="1" fontSize="16" title="100%" /> </span> ``` At 0% the word is entirely the muted track; at 100% it is entirely accent ink — both ends are honest limits of the same clip, not a special case. ```tsx `"> <FillWord value="0.5" fontSize="16" title="Empty" /> ``` An empty `word` renders nothing and reports **"No data."** — there is no label to be the bar. ## Why this default [#why-this-default] Fill (not drain) is the default because progress is the ninety-percent case — a word filling as a step completes. `mode="drain"` empties the ink from the left as the value rises, the remaining-time story that fill cannot tell (TTLs, expiring sessions). Because glyph ink is uneven, fine reads are ±5% — the fill edge lands between letters, not on an exact tick. When you need the number, add `label="value"` for the percent alongside, or reach for `Progress` when precision is the point. ## Accessibility [#accessibility] The accessible name names the task and its state — **"storage: 40% complete."** — or, in drain mode, where `value` is the fraction already drained, **"expiring: 30% remaining."** for `value={0.7}`. An empty word reads "No data." The interactive entry glides the ink edge with a reduced-motion-gated clip-path transition and announces changes through a polite live region, throttled to at most once a second so a streaming value never spams. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `word` (required) | `string` | The text that is the chart. | | `value` (required) | `number` | Fraction 0–1 (clamped). | | `mode` | `"fill" \| "drain"` | fill grows the ink (complete); drain empties it (remaining / TTL). | | `label` | `"none" \| "value"` | Append the percent numeral after the word. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # FoldedDayBand (/docs/charts/folded-day-band) FoldedDayBand answers "what does a typical period look like — and is the current one typical?". It folds many days (or weeks, or any cycle) onto a single period axis and shows the median with 25–75 and 5–95 percentile envelopes. Drop in a `today` overlay and the chart answers the second question: is right now inside the usual band, or an outlier? ```tsx 40 + 42 _ Math.max(0, 1 - Math.abs(h - 14) / 10); const observations = Array.from({ length: 14 }, (\_d, d) => Array.from({ length: 24 }, (\_h, h) => ({ t: d _ 24 + h, value: Math.round(curve(h) + Math.sin(d + h) \* 8), })), ).flat(); const today = Array.from({ length: 24 }, (\_h, h) => ({ t: h, value: Math.round(curve(h) + 14), })); <FoldedDayBand data={observations} today={today} title="Typical day" />`" > <FoldedDayBand data="Array.from({ length: 14 }, (_d, d) => Array.from({ length: 24 }, (_h, h) => ({ t: d * 24 + h, value: Math.round(40 + 42 * Math.max(0, 1 - Math.abs(h - 14) / 10) + Math.sin(d + h) * 8) }))).flat()" today="Array.from({ length: 24 }, (_h, h) => ({ t: h, value: Math.round(40 + 42 * Math.max(0, 1 - Math.abs(h - 14) / 10) + 14) }))" title="Typical day" width="300" height="40" /> ``` ## Install [#install] ```tsx import { FoldedDayBand } from "@microcharts/react/folded-day-band"; <FoldedDayBand data={observations} today={today} title="Typical day" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — typical-day traffic or load profiles, on-call or energy capacity planning. * **Avoid for** — a raw time series (Sparkline) or a single period with nothing to fold. ## Variants [#variants] ```tsx <FoldedDayBand data={observations} format={{ minimumFractionDigits: 1, maximumFractionDigits: 1 }} locale="de-DE" />`" > <span className="inline-flex flex-col gap-3"> <FoldedDayBand data="Array.from({ length: 14 }, (_d, d) => Array.from({ length: 24 }, (_h, h) => ({ t: d * 24 + h, value: Math.round(40 + 42 * Math.max(0, 1 - Math.abs(h - 14) / 10) + Math.sin(d + h) * 8), })), ).flat()" percentiles="[[25, 75]]" title="Middle half only" width="300" height="40" /> <FoldedDayBand data="Array.from({ length: 14 }, (_d, d) => Array.from({ length: 24 }, (_h, h) => ({ t: d * 24 + h, value: Math.round(40 + 42 * Math.max(0, 1 - Math.abs(h - 14) / 10) + Math.sin(d + h) * 8), })), ).flat()" format="{ minimumFractionDigits: 1, maximumFractionDigits: 1 }" locale="de-DE" title="Localized peak" width="220" height="32" /> </span> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, the accessible summary's fold position and peak value follow that locale's own decimal mark ("14,0" in German, not "14.0"). The band and median line themselves don't change shape; only the announced numbers are localized. ## Edge cases [#edge-cases] ```tsx `"> <FoldedDayBand data="[{ t: 3, value: 10 }]" title="Single observation" width="160" height="32" /> ``` ```tsx ({ t: i, value: 7 }))} />`" > <FoldedDayBand data="Array.from({ length: 48 }, (_v, i) => ({ t: i, value: 7 }))" title="Flat" width="200" height="32" /> ``` A single observation reports a real accessible name (median and peak both equal that one value) but has no width to fold across, so nothing visibly paints — the chart is accessible-first even when there's too little data to draw. Identical values across every bin still render as a flat line, distinct from an empty `data` array, which renders nothing and announces "No data." ## Why this default [#why-this-default] Two envelopes plus a median is the typical-day grammar that clinical glucose profiles standardized on. The envelopes come from real per-bin quantiles — never smoothed across bins into a shape the data doesn't support — and the outer boundary fades so 5–95 doesn't read as a hard limit. When a bin has too few observations the band collapses to the median there rather than inventing a width. ## Accessibility [#accessibility] The accessible name reports the peak — **"Median peaks at 14 (82.5)."** The interactive entry roves the folded axis with ←/→, announcing the median and middle-half at each position. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ t, value }[]` | Raw observations across many periods. | | `period` | `number` | Fold length (168 folds a week). | | `today` | `{ t, value }[]` | The current period overlaid. | | `percentiles` | `[number, number][]` | Percentile pairs, outermost last. | | `bins` | `number` | Fold-axis resolution (default 24). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # ForecastCone (/docs/charts/forecast-cone) ForecastCone answers "will we land where we need to?". History is a solid line; the forecast is a fan of prediction bands that **widen over the horizon**, with a **dashed** median — because an estimate should never render as fact. The whole point of a fan chart is visible confidence decay, so three rules are not style options: at most two bands (50/80 — a 95% band reads as false tail confidence at micro scale), the median is always dashed, and a cone that fails to widen is flagged, never quietly inflated. ```tsx <ForecastCone data="[30, 32, 31, 34, 36, 35, 38]" forecast="{ mid: [39, 40, 41, 42], p80: [ [36, 42], [35, 45], [34, 50], [33, 55], ], p50: [ [37, 41], [37, 43], [36, 46], [35, 49], ], }" target="45" label="landing" title="Q4 revenue" width="260" height="28" /> ``` ## Install [#install] ```tsx import { ForecastCone } from "@microcharts/react/forecast-cone"; <ForecastCone data={history} forecast={forecast} target={45} title="Q4 revenue" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a "will we hit Q4?" forecast in a KPI card, a projection with honest uncertainty in a sentence, band-vs-target landing reads. * **Avoid for** — a forecast with no uncertainty (Sparkline) or one estimate's spread (GradedBand). ## Variants [#variants] ```tsx `" > <span className="inline-flex flex-col gap-1.5"> <ForecastCone data="[30, 32, 31, 34, 36, 35, 38]" forecast="{ mid: [39, 40, 41, 42], p80: [ [36, 42], [35, 45], [34, 50], [33, 55], ], }" title="Single band" width="220" height="26" /> <ForecastCone data="[30, 32, 31, 34, 36, 35, 38]" forecast="{ mid: [39, 40, 41, 42], p80: [ [36, 42], [35, 45], [34, 50], [33, 55], ], p50: [ [37, 41], [37, 43], [36, 46], [35, 49], ], }" target="50" title="Vs a higher target" width="220" height="26" /> </span> ``` ```tsx `" > <ForecastCone data="[3000, 3200, 3100, 3400, 3600, 3500, 3800]" forecast="{ mid: [3900, 4000, 4100, 4200], p80: [ [3600, 4200], [3500, 4500], [3400, 5000], [3300, 5500], ], }" format="{ style: "currency", currency: "EUR", maximumFractionDigits: 0 }" locale="de-DE" title="Localized forecast" width="220" height="26" /> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, the in-chart landing label and the accessible summary's median, interval, and target numbers all follow that locale's own grouping and currency placement (the label above reads "4.200 €", not "€4,200"). ## Edge cases [#edge-cases] ```tsx `" > <ForecastCone data="[]" forecast="{ mid: [10, 12, 14], p80: [ [8, 12], [8, 15], [7, 19], ], }" title="No history" width="160" height="26" /> ``` ```tsx `" > <ForecastCone data="[10, 11]" forecast="{ mid: [12, 13, 14], p80: [ [9, 15], [10, 14], [11, 13], ], }" title="Narrowing input" width="160" height="26" /> ``` With no history the cone still draws from the first forecast point, and the accessible summary quietly drops its "from N today" clause instead of naming a value that doesn't exist. A cone whose bands narrow instead of widen is an input-honesty failure — it renders exactly as supplied (never auto-inflated to look right) and logs a one-time dev warning so the mistake surfaces in development rather than silently misleading a reader. ## Why this default [#why-this-default] 50/80 bands, not 95, because micro-scale tails invite overreading — a 95% band paints false confidence about the extremes. The median is dashed so it never reads as a committed number, and the cone must visibly widen: if the supplied bands don't (they narrow, or stay flat), that is an input-honesty failure the component surfaces rather than papering over — a forecast whose uncertainty doesn't grow with the horizon is misrepresenting confidence decay. ## Accessibility [#accessibility] The accessible name states the median, the horizon interval, today's actual, and — with a target — whether the band clears it: **"Median forecast 42 by week 11 (80% between 33 and 55), from 38 today. The 80% band straddles the 50 target."**. The interactive entry is region-aware: history points announce a value, forecast points announce the median and 80% interval. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Historical actuals. | | `forecast` (required) | `{ mid: number[]; p80: [lo,hi][]; p50?: [lo,hi][] }` | Median + prediction bands (at most 2: 50/80). | | `target` | `number` | The landing reference the cone must clear (adds a clearance clause). | | `unit` | `string` | Period noun for the summary (default "week"). | | `label` | `"landing" \| "none"` | Median endpoint value in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Funnel (/docs/charts/funnel) Funnel answers "where does the pipeline leak?". Stepped rectangles, zero-anchored — never the classic tapered silhouette, which interpolates data that doesn't exist. The drop *between* neighbors is the read. ```tsx <Funnel data="[ { label: "Visitors", value: 12400 }, { label: "Signups", value: 5704 }, { label: "Activated", value: 2730 }, { label: "Paid", value: 1116 }, ]" title="Signup funnel" width="220" height="66" /> ``` ## Install [#install] ```tsx import { Funnel } from "@microcharts/react/funnel"; <Funnel data={stages} title="Signup funnel" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — per-campaign funnels in table cells, conversion bridges in cards. * **Avoid for** — unordered categories (MiniBar) or more than 6 stages. ## Variants [#variants] ```tsx `" > <Funnel data="[ { label: "Visitors", value: 12400 }, { label: "Signups", value: 5704 }, { label: "Paid", value: 1116 }, ]" mode="rate" title="Rate" width="220" height="66" /> ``` ```tsx `" > <Funnel data="[ { label: "Visitors", value: 12400 }, { label: "Signups", value: 5704 }, { label: "Activated", value: 2730 }, { label: "Paid", value: 1116 }, ]" highlight="Activated" title="The leak" width="220" height="66" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <Funnel data="[{ label: "Visitors", value: 8000 }]" title="Single stage" width="120" height="40" /> ``` ```tsx `" > <Funnel data="[ { label: "Trial", value: 900 }, { label: "Churned", value: 420 }, { label: "Win-back", value: 610 }, ]" title="Re-engagement funnel" width="220" height="56" /> ``` ## Why this default [#why-this-default] `rate` always normalizes to stage 1, never to the previous stage — per-stage rates hide compounding loss. A stage larger than its predecessor (re-engagement funnels) renders truthfully and the summary appends the inversion. The connectors and zero-anchored columns keep the read a measurement, not a shape. ## Accessibility [#accessibility] The accessible name is the conversion story — **"4 stages, 12,400 to 1,116 — overall 9%."**, plus **"Stage 3 exceeds stage 2."** when a pipeline inverts. The interactive entry roves stages (**"Activated: 2,730 — 22% of Visitors."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value }[]` | Ordered stages. | | `mode` | `"absolute" \| "rate"` | Rate = % of the FIRST stage (never the previous). | | `connectors` | `boolean` | Retained-share slats between stages. | | `label` | `"none" \| "percent" \| "value"` | Above each column (deterministic drop-out; default percent). | | `highlight` | `number \| string` | Accent the leak stage. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # GardenGrid (/docs/charts/garden-grid) GardenGrid answers "what's the rhythm of activity over time?" the way ActivityGrid does — but with a single ink. Instead of color, dot **area** carries a five-step ordinal, so the rhythm reads in grayscale and print where a color heatmap would collapse. The radius is √-quantized so perceived area steps evenly. A zero cell is a hairline ring (present, but quiet); a `null` cell is nothing at all, because "missing" is not "zero". ```tsx <GardenGrid data="[12, 20, 8, 0, 15, 28, 34, 5, 0, 22, 18, 9, 3, 0, 24, 30, 11, 6, 19, 0, 26]" unit="weeks" title="Activity" cell="11" /> ``` ## Install [#install] ```tsx import { GardenGrid } from "@microcharts/react/garden-grid"; <GardenGrid data={weeks} title="Activity" unit="weeks" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a contribution or activity rhythm you print or read in grayscale, a per-repo or per-team activity strip, or any calendar-shaped intensity where color isn't available. * **Avoid for** — exact per-cell values (ActivityGrid with hover, or HeatStrip) or trends (Sparkline). ## Variants [#variants] ```tsx <GardenGrid data={weeks} empty="blank" />`" > <span className="inline-flex flex-col gap-3"> <GardenGrid data="[12, 20, 8, 0, 15, 28, 34, 5, 0, 22, 18, 9]" rows="1" cell="11" /> <GardenGrid data="[12, 20, 8, 0, 15, 28, 34, 5, 0, 22, 18, 9, 3, 0]" empty="blank" cell="11" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <GardenGrid data="[]" title="No history" cell="11" /> ``` ```tsx `"> <GardenGrid data="[0, 0, 0, 0, 0, 0, 0]" title="Quiet week" cell="11" /> ``` ```tsx `"> <GardenGrid data="[5, null, 8, null, null, 3]" title="Gaps" cell="11" /> ``` ```tsx `"> <GardenGrid data="[12]" title="One" cell="11" /> ``` ## Why this default [#why-this-default] Rings for zero are the default because print and grayscale lose the zero-versus-missing distinction that color grids get for free — this chart exists for exactly that medium, so it makes "present but quiet" visible. The radius is √-quantized so **area** carries the ordinal; a linear radius map would exaggerate the highs quadratically. The steps are ordinal, not values — the interactive entry announces a cell's step rather than implying a precise read, and `ActivityGrid` is the color twin when exact values matter. ## Accessibility [#accessibility] The accessible name summarizes the rhythm — **"12 periods; peak 34, 10 active."** The interactive entry walks the grid in 2-D with the arrow keys (or hover), announcing each cell as its ordinal step — **"3 of 21: 8, step 2 of 5."** — never a false-precise value, since dot area reads to a step, not a number. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | Binned values; null = missing. | | `rows` | `number` | Grid rows (default 7); 1 = strip. | | `steps` | `3 \| 5` | Radius quantization steps (default 5). | | `empty` | `"outline" \| "blank"` | How zero cells render (default outline). | | `unit` | `string` | Noun for the summary count (default "periods"). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # GradeProfile (/docs/charts/grade-profile) GradeProfile answers "how hard is this route, and where does it bite?" Each segment between two points is filled from the baseline and coloured by its grade — gentle to brutal — with the elevation ridge riding on top. The steepest pitch is called out, so the wall in the route is the first thing you see. **How to read it** — colour is a *quantized* grade bin, never a smooth ramp: flats and every descent take the faint band, then a mid tone, the negative colour, and the darkest fill for the brutal pitches. Height is the elevation ridge for shape; the encoded channel is the colour, and the interactive readout gives the exact grade. ```tsx <GradeProfile data="[ { d: 0, elev: 800 }, { d: 100, elev: 809 }, { d: 250, elev: 812 }, { d: 350, elev: 817 }, { d: 500, elev: 835 }, { d: 700, elev: 833 }, { d: 900, elev: 865 }, ]" format="{ style: "unit", unit: "meter", unitDisplay: "short" }" title="Queen stage" width="240" height="48" /> ``` `d` and `elev` must share a unit (both metres, say) so that grade — rise ÷ run — is a true percent. Distance need only be monotonic; the values themselves can be any scale. ## Install [#install] ```tsx import { GradeProfile } from "@microcharts/react/grade-profile"; <GradeProfile data={trail} format={(n) => `${n} m`} title="Queen stage" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — route and climb profiles (cycling, running, hiking); showing *where* the hard pitches fall. * **Avoid for** — a single elevation series (Sparkline), or an unordered track (distance must be monotonic). ## Variants [#variants] ```tsx `" > <GradeProfile data="[ { d: 0, elev: 800 }, { d: 250, elev: 812 }, { d: 500, elev: 835 }, { d: 700, elev: 833 }, { d: 900, elev: 865 }, ]" label="none" title="No label" width="240" height="44" /> ``` ```tsx `" > <GradeProfile data="[ { d: 0, elev: 800 }, { d: 100, elev: 809 }, { d: 350, elev: 817 }, { d: 500, elev: 835 }, { d: 900, elev: 865 }, ]" bins="[5, 8, 12]" format="{ style: "unit", unit: "meter", unitDisplay: "short" }" title="Custom bins" width="240" height="44" /> ``` ```tsx `" > <GradeProfile data="[ { d: 0, elev: 600 }, { d: 2000, elev: 780 }, { d: 5000, elev: 1150 }, { d: 8000, elev: 1400 }, { d: 12000, elev: 1850 }, ]" format="{ maximumFractionDigits: 0 }" locale="de-DE" title="Alpine stage" width="240" height="48" /> ``` `format` accepts `Intl.NumberFormatOptions` (with a `locale`) or a formatting function, and applies to **distance and elevation** numbers in the summary and readout — not grade. Grades are always percent-encoded; the locale still decides the decimal mark: the alpine profile above reads **"12.000, 1.250 gain; steepest 12,3% at 3.500."** in German. ## Edge cases [#edge-cases] ```tsx \`\${n} m\`} title="Descent" />`" > <GradeProfile data="[ { d: 0, elev: 900 }, { d: 300, elev: 840 }, { d: 600, elev: 780 }, ]" format="{ style: "unit", unit: "meter", unitDisplay: "short" }" title="Descent" width="200" height="44" /> ``` ```tsx `" > <GradeProfile data="[ { d: 0, elev: 100 }, { d: 100, elev: 120 }, { d: 200, elev: NaN }, { d: 300, elev: 160 }, ]" title="Partial track" width="200" height="44" /> ``` A descent-only route has no climb to grade, so no pitch is emphasised and the summary reports **"600 m, no real climb."** — climbing difficulty is the whole story, so descents always take the gentlest colour rather than borrowing a climb's. A non-finite elevation breaks the profile into a gap: the segments touching it drop out and the ridge splits, so a missing reading never invents a grade. A flat route reports the "no real climb" sentence too, and a single point has no segment to grade at all, so its accessible name falls back to **"No data."** ## Why this default [#why-this-default] Two decisions carry the chart. Grade is **quantized** into bins, not drawn as a continuous colour ramp — a route reads as "gentle / rolling / steep / wall", categories a rider can act on, instead of a gradient nobody can decode at a glance. And the default `bins` of `[3, 6, 10]` percent match how climbs are actually described, with the steepest pitch labelled so the hardest moment is never buried. Below 72 pixels wide the four bins collapse to a simple flat-versus-climb read, because the finer classes stop being separable there. ## Accessibility [#accessibility] The accessible name states the route's shape in words — **"900, 67 gain; steepest 16% at 800."** — distance, total climb, and where the hardest pitch falls, none of it dependent on colour. The interactive entry announces each pitch as you rove it (`←`/`→`), giving the true grade and the cumulative climb, so the encoding never has to be learned to be used. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ d: number; elev: number }[]` | Distance + elevation, monotonic in d, same unit so grade is a true percent. | | `bins` | `[number, number, number]` | Ascending grade-% thresholds (always percent) that quantize the four difficulty bins. | | `format` | `Intl.NumberFormatOptions \| (n) => string` | Formats distance and elevation in the summary and readout; grades always render as percent. | | `label` | `"max" \| "none"` | Mark the steepest pitch, or render the profile alone. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # GradedBand (/docs/charts/graded-band) GradedBand answers "how sure are we about this one number?". Nested central intervals are graded by opacity, with a median tick. It is **never** a bar from zero — a bar with an error bar induces edge-literalism bias, so this form exists precisely to avoid it. Opacity maps to probability level and nothing else. ```tsx <GradedBand data="Array.from({ length: 160 }, (_, i) => 21 + Math.round(9 * Math.sin(i) + 6 * Math.sin(i * 2.3)))" label="median" title="Forecast estimate" width="240" height="16" /> ``` ## Install [#install] ```tsx import { GradedBand } from "@microcharts/react/graded-band"; <GradedBand data={posterior} label="median" title="Forecast estimate" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a forecast with its uncertainty, estimate-vs-actual in a KPI card, posterior summaries. * **Avoid for** — countable odds (QuantileDots) or a forecast over time (ForecastCone). ## Variants [#variants] ```tsx 21 + Math.round(9 * Math.sin(i) + 6 * Math.sin(i * 2.3)), ); <GradedBand data={posterior} value={28} /> <GradedBand data={posterior} softEdge />`" > <span className="inline-flex flex-col gap-1.5"> <GradedBand data="Array.from( { length: 160 }, (_, i) => 21 + Math.round(9 * Math.sin(i) + 6 * Math.sin(i * 2.3)), )" value="28" title="Estimate vs actual" width="200" height="14" /> <GradedBand data="Array.from( { length: 160 }, (_, i) => 21 + Math.round(9 * Math.sin(i) + 6 * Math.sin(i * 2.3)), )" title="Soft edge" width="200" height="14" /> </span> ``` ```tsx (21 + Math.round(9 * Math.sin(i) + 6 * Math.sin(i * 2.3))) / 10, ); <GradedBand data={drift} label="median" locale="de-DE" />`" > <GradedBand data="Array.from( { length: 160 }, (_, i) => (21 + Math.round(9 * Math.sin(i) + 6 * Math.sin(i * 2.3))) / 10, )" label="median" locale="de-DE" title="Localized median" width="200" height="14" /> ``` With a `locale`, the median label and the accessible summary follow that locale's decimal mark — the label above renders "2,2", not "2.2". ## Edge cases [#edge-cases] ```tsx `" > <GradedBand data="[42, 42, 42, 42, 42, 42]" title="No spread" width="200" height="14" /> ``` The accessible name for that strip is **"Point value 42, no interval."** — a degenerate sample is announced as a point estimate, never dressed up as certainty about a range. ```tsx `" > <GradedBand data="[19, 20, 21, 21, 22, 22, 23, 23, 24, 26]" value="48" title="Forecast miss" width="200" height="14" /> ``` ## Why this default [#why-this-default] Nested central intervals graded by opacity — never a bar from zero. A bar with an error whisker invites reading the bar's end as "the answer" and the whisker as noise; the graded band has no endpoint to over-read, so opacity maps to probability and nothing else. Inner intervals are clipped inside their outer, so quantile rounding can never invert the nesting. ## Accessibility [#accessibility] The accessible name states the median and the innermost + outermost intervals — for the forecast above that's **"Median 22; 50% within 15–27, 95% within 8–36."** The interactive entry roves the band edges and announces each interval's coverage and bounds. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Sample / posterior draws; the component derives the intervals. | | `levels` | `number[]` | 1–3 nested central intervals (default [50, 80, 95]). | | `value` | `number` | Observed value overlaid as a dot. | | `softEdge` | `boolean` | Fade past the outer band — 'this is approximate'. | | `label` | `"median" \| "none"` | States the median in a right gutter (default none). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # HeartbeatBlip (/docs/charts/heartbeat-blip) HeartbeatBlip answers "is it alive, and how busy?" at a glance. Each event in the recent window is an ECG-style spike; in the interactive entry the trace sweeps left in real time and a new event blips in at the right edge, so the rate you see **is** the event rate. Every spike is one real event — never a synthesized pulse on a timer — and an empty, flat baseline is the down signal, carried by shape, not color. ```tsx <HeartbeatBlip events="[97000, 92000, 85000, 70000, 55000, 48000]" now="100000" title="Requests" width="90" /> ``` ## Install [#install] ```tsx import { HeartbeatBlip } from "@microcharts/react/heartbeat-blip"; // pass 'now' from your data layer — never Date.now() in a server render <HeartbeatBlip events={eventTimestamps} now={serverNow} title="Requests" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## Motion, and reduced motion [#motion-and-reduced-motion] The trace advances in real time so old spikes drift left and new events enter at the right — the liveness comes from watching the blips arrive. This is the deliberate idle-loop exception, allowed because the loop parameter (elapsed time) is the datum. It pauses off-screen (a shared observer) and, under `prefers-reduced-motion`, does not sweep at all: the static strip simply re-renders on each data change — the same information, discretely updated. The one rule this chart must never break: **a flat service never gets a fake pulse.** Every spike is a real event; when the window empties, the baseline goes flat and stays flat. ## When to use it [#when-to-use-it] * **Good for** — at-a-glance liveness of a service or stream, request rate in a header, or per-service liveness in a status table. * **Avoid for** — exact event counts (`Seismogram`, `EventTimeline`), a continuous level (`BreathingDot`), or long-term trends (`Sparkline`). ## Sizing [#sizing] `width` and `height` are viewBox units that also set the rendered pixel box — they default to `60 × 16`, sized to sit in a status table row or a header. Omit them and drive the width from CSS to fill a column; the viewBox keeps the aspect ratio. `window` sets how much time the strip covers, which changes the density of the trace rather than its box. ## Variants [#variants] ```tsx <HeartbeatBlip events={[]} now={serverNow} />`" > <span className="inline-flex gap-6 items-center"> <HeartbeatBlip events="[97000, 92000, 85000, 70000, 55000, 48000]" now="100000" label="count" width="90" summary="false" /> <HeartbeatBlip events="[]" now="100000" width="90" summary="false" /> </span> ``` ```tsx `" > <HeartbeatBlip events="[97000, 92000, 85000]" now="100000" label="count" format="{ useGrouping: false }" locale="de-DE" title="Requests" width="90" /> ``` `format`/`locale` only reach the `label="count"` numeral — the accessible summary's count is a plain integer (never run through the formatter), and the in-chart spikes never carry text, so there's nothing else to localize. ## Edge cases [#edge-cases] ```tsx `"> <HeartbeatBlip events="[]" now="100000" title="Requests" width="90" /> ``` ```tsx `"> <HeartbeatBlip events="[97000, Number.NaN, 92000]" now="100000" title="Requests" width="90" /> ``` ```tsx `" > <HeartbeatBlip events="[95000, 10000]" now="100000" title="Requests" width="90" /> ``` ## Why this default [#why-this-default] The 60-second window is the default because liveness questions are about the last minute. The `now` clock is a required-in-spirit prop: the static entry must never call `Date.now()` (a server render and the client hydrate would disagree and mismatch), so you pass the clock from your data layer. Flatline is never dressed up — down and no-data are different states, and the summary distinguishes them. The boundary with `BreathingDot`: discrete arriving events are a HeartbeatBlip; a continuous level is a BreathingDot. ## Accessibility [#accessibility] The accessible name is the count, the window, and the time since the last event — **"3 events in the last minute; last 3s ago."** — or **"No events in the last minute."** when the trace is flat. The trace sweeps only when motion is allowed and on-screen; the live region announces on data change, and there is no per-spike navigation because the spikes are transient — the summary is the record. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `events` (required) | `number[]` | Event timestamps (ms). | | `window` | `number` | The visible recent window in ms (default 60000). | | `now` | `number` | Explicit clock — defaults to the latest event (SSR-safe). | | `label` | `"count" \| "none"` | Event-count numeral at the right. | 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](/docs/quickstart#the-shared-grammar). # HeatCell (/docs/charts/heat-cell) HeatCell answers "how intense is this one value against a known scale?". It is the single-cell building block for grids you lay out yourself — a matrix of tenants × hours, a custom calendar, a density chip in a sentence. Color is quantized into discrete steps: continuous opacity would fake precision a 12-px cell can't deliver. ```tsx <span className="inline-flex items-center gap-1.5"> {[12, 35, 58, 79, 96].map((v) => ( <HeatCell key={v} value={v} domain={[0, 100]} title={`Load ${v}`} style={{ width: 18, height: 18 }} /> ))} </span> ``` ## Install [#install] ```tsx import { HeatCell } from "@microcharts/react/heat-cell"; <HeatCell value={42} domain={[0, 100]} title="Load" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — table-cell matrices, custom grids, intensity chips beside labels. * **Avoid for** — precise comparison (MiniBar, DotPlot) or time series (HeatStrip, ActivityGrid). ## The shared-domain rule [#the-shared-domain-rule] A lone cell has no data to auto-scale from, so `domain` defaults to `[0, 1]` — pass your grid's real scale. **Every cell in one grid must share one domain**: per-cell auto-scaling would make the brightest hour of a quiet tenant look like the brightest hour of a loud one. ```tsx // one domain, computed once, shared by every cell const domain: [number, number] = [0, Math.max(...allValues)]; rows.map((r) => r.hours.map((v) => <HeatCell value={v} domain={domain} />)); ``` ## Variants [#variants] ```tsx <HeatCell value={70} domain={[0, 100]} shape="round" /> <HeatCell value={70} domain={[0, 100]} shape="dot" />`" > <span className="inline-flex items-center gap-1.5"> <HeatCell value="70" domain="[0, 100]" title="Square" style="{ width: 18, height: 18 }" /> <HeatCell value="70" domain="[0, 100]" shape="round" title="Round" style="{ width: 18, height: 18 }" /> <HeatCell value="70" domain="[0, 100]" shape="dot" title="Dot" style="{ width: 18, height: 18 }" /> </span> ``` ```tsx `"> <HeatCell value="8" domain="[0, 9]" label="value" title="Intensity" style="{ width: 28, height: 28 }" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <HeatCell value="Number.NaN" domain="[0, 100]" title="No data" style="{ width: 18, height: 18 }" /> ``` ```tsx <HeatCell value={140} domain={[0, 100]} />`" > <span className="inline-flex items-center gap-1.5"> <HeatCell value="-20" domain="[0, 100]" title="Below floor" style="{ width: 18, height: 18 }" /> <HeatCell value="140" domain="[0, 100]" title="Above ceiling" style="{ width: 18, height: 18 }" /> </span> ``` ## Why this default [#why-this-default] Five steps is the most a reader reliably distinguishes at cell size — the same ramp ActivityGrid uses, so intensity means one thing across the library. Values outside the domain clamp to the end steps (documented, never silently rescaled), and a zero-width domain renders the single mid step with a dev warning. ## Accessibility [#accessibility] The accessible name carries the value *and* its calibration — the shape cells above read **"70 — level 4 of 5."** — so the color scale is never the only channel. Non-finite input renders a designed empty track and says **"No data."** The interactive entry reveals the same reading on hover/focus, with ActivityGrid announcement parity. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The value to calibrate. | | `domain` | `[number, number]` | Calibration scale — defaults to [0, 1]; every cell in a grid must share one. | | `steps` | `number` | Discrete perceptual steps (default 5, shared with ActivityGrid). | | `shape` | `"square" \| "round" \| "dot"` | Shared cell vocabulary. | | `label` | `"value" \| "none"` | Centered number when the cell doubles as a chip. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # HeatStrip (/docs/charts/heat-strip) HeatStrip answers "how did intensity evolve, glanceably?". It is the 1×N sibling of ActivityGrid: the same discrete step scale, the same cell vocabulary, laid on a single timeline. Empty is not zero — a slot with no record renders a hairline outline, visibly different from a low value. ```tsx <HeatStrip data="[12, 25, 38, 52, 66, 79, 88, 90, 84, 71, 55, 40, 28, 45, 62, 78, 85, 74, 58, 35]" domain="[0, 100]" title="Load per hour" width="240" height="20" /> ``` ## Install [#install] ```tsx import { HeatStrip } from "@microcharts/react/heat-strip"; <HeatStrip data={hourlyLoad} domain={[0, 100]} title="Load per hour" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — per-tenant load rows, intensity ribbons in dense tables. * **Avoid for** — exact shape (Sparkline) or weekday rhythm (ActivityGrid). ## Variants [#variants] ```tsx <HeatStrip data={load} domain={[0, 100]} shape="dot" />`" > <span className="inline-flex flex-col gap-1.5"> <HeatStrip data="[12, 38, 66, 88, 84, 55, 28, 62, 85, 58]" domain="[0, 100]" shape="round" title="Round" width="160" height="14" /> <HeatStrip data="[12, 38, 66, 88, 84, 55, 28, 62, 85, 58]" domain="[0, 100]" shape="dot" title="Dot" width="160" height="14" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <HeatStrip data="[3, null, 8, null, 5]" title="Gaps" width="100" height="16" /> ``` ## Why this default [#why-this-default] Square cells with a density-adaptive gap keep boundaries legible where round shapes blur at 10 px. Every real value renders at a visible opacity (0.25–1); the faint track look is reserved for truly-empty slots. Three ways a heat strip lies — continuous ramps, per-row autoscale, mean-based downsampling — are all closed: discrete steps, shared `domain`, max-per-bucket only. ## Accessibility [#accessibility] The summary reuses `describeSeries` verbatim — for the load strip above that's **"Trending up 383%. Range 12 to 88. Last value 58."** — so a color ramp is never the only channel. The interactive entry roves cells with ActivityGrid-parity announcements (**"Point 8 of 20: 90."**, empty slots as "no data"). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | Time-ordered values; null = no record (≠ zero). | | `steps` | `number` | Shared step-scale granularity (default 5). | | `shape` | `"square" \| "round" \| "dot"` | Shared cell vocabulary. | | `domain` | `[number, number]` | Cross-row calibration — share one domain per table. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # HistogramStrip (/docs/charts/histogram-strip) HistogramStrip answers "what does the distribution look like?". Raw observations in, ≤ 12 uniform bins out — counts zero-anchored, never density-smoothed. Pre-aggregated counts are not supported; that's SparkBar's contract. ```tsx <HistogramStrip data="Array.from({ length: 120 }, (_, i) => (i % 3 === 0 ? 40 + (i % 10) : 20 + ((i * 7) % 60)))" title="Response times" style="{ width: 220, height: 56 }" /> ``` ## Install [#install] ```tsx import { HistogramStrip } from "@microcharts/react/histogram-strip"; <HistogramStrip data={times} title="Response times" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — latency clusters in a sentence, distributions per table row. * **Avoid for** — raw marks (RugStrip) or series over time (Sparkline). ## Variants [#variants] ```tsx i % 3 === 0 ? 40 + (i % 10) : 20 + ((i * 7) % 60), ); <HistogramStrip data={responseTimes} markValue={45} title="You are here" />`" > <HistogramStrip data="Array.from({ length: 120 }, (_, i) => i % 3 === 0 ? 40 + (i % 10) : 20 + ((i * 7) % 60), )" markValue="45" title="You are here" style="{ width: 220, height: 56 }" /> ``` ```tsx `" > <HistogramStrip data="[12000, 18000, 24000, 30000, 36000, 42000, 18000, 24000, 30000]" locale="de-DE" title="Localized bin edges" style="{ width: 220, height: 56 }" /> ``` The accessible summary states the modal bin's edges through `format`/`locale` — under `de-DE` a value like 24000 reads "24.000" (period as the thousands separator) instead of the English "24,000". ## Edge cases [#edge-cases] ```tsx `"> <HistogramStrip data="[]" title="No observations yet" style="{ width: 160, height: 40 }" /> ``` ```tsx `"> <HistogramStrip data="[4, 4, 4, 4, 4]" title="Constant" style="{ width: 160, height: 40 }" /> ``` An empty series renders zero bars and an accessible name of "No data." rather than a misleading flat line. A constant series collapses to ONE full-height bin instead of the usual up-to-12 slivers a naive equal-width binner would draw for a zero-span domain. ## Why this default [#why-this-default] Auto bin count is √n capped at 12 — enough shape to see skew, few enough bars to survive 60 px. All values identical collapse to ONE bin (never twelve slivers); explicit bin counts collapse to the observation count. `markValue` marks the bin of a value and never re-bins around it. ## Accessibility [#accessibility] The accessible name names the modal bin — **"120 values, most between 42.09 and 47.36."** The interactive entry roves bins with range announcements (**"42.09 to 47.36: 26 values."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Raw observations. | | `bins` | `number` | Bin count; auto = min(12, √n). | | `markValue` | `number` | A VALUE whose bin gets accent. | | `domain` | `[number, number]` | Fixed bin edges across multiples. | | `format` | `Intl.NumberFormatOptions \| fn` | Formats the bin edges named in the summary. | | `locale` | `string \| string[]` | BCP 47 locale(s) for the formatted bin edges. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Honeycomb (/docs/charts/honeycomb) Honeycomb answers "how many of the available slots are taken?" as filled cells in an area-filling hex grid. The unit is the cell, so the count is genuinely countable — this is occupancy of a capacity, not a magnitude. It fills row-major from the top-left, so occupancy reads as a sweep, and the whole grid is exactly two SVG paths (filled and empty) no matter how large the total. ```tsx <Honeycomb value="34" total="40" unit="seats" title="Occupancy" cell="6" /> ``` ## Install [#install] ```tsx import { Honeycomb } from "@microcharts/react/honeycomb"; <Honeycomb value={34} total={40} unit="seats" title="Occupancy" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — seats or licenses taken of a capacity, an occupancy read in a KPI card, or a countable of-total in a cell. * **Avoid for** — a capacity over about sixty (that's `Progress`), a magnitude with no total (MiniBar), or trends. ## Variants [#variants] ```tsx <Honeycomb value={28} total={40} empty="blank" />`" > <span className="inline-flex gap-6 items-center"> <Honeycomb value="7" total="10" rows="1" cell="6" /> <Honeycomb value="28" total="40" empty="blank" cell="5" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <Honeycomb value="0" total="12" unit="seats" title="Empty" cell="6" /> ``` ```tsx `"> <Honeycomb value="45" total="40" unit="seats" title="Overbooked" cell="6" /> ``` ```tsx `"> <Honeycomb value="0" total="0" title="No capacity" cell="6" /> ``` ## Why this default [#why-this-default] Outline empties are the default because takenness must survive grayscale — a filled cell versus an outlined cell reads without color. `empty="blank"` drops the empty cells entirely instead of dimming them, for surfaces where the outline reads as noise. Auto packing is the default because a near-square honeycomb is the recognizable form. The unit is the cell, and its size never changes with value — the count varies, the geometry doesn't — which is what keeps this honest area-filling *occupancy*, distinct from a `PictogramRow` counting unlike things. Above sixty cells, unit counting stops being countable, so the chart emits a dev warning and the docs steer to `Progress`. A value past the total fills every cell, but the accessible name still states the true number — occupancy is never silently clipped. ## Accessibility [#accessibility] The accessible name is the exact occupancy — **"45 of 40 seats filled."** — always the true value, even when it exceeds the total. The interactive entry announces the count on change through a polite live region and reveals the value / total on hover. Focus it and the arrow keys rove cell by cell (←/→ within a row, ↑/↓ holding the column), each cell announced as **"Cell 7 of 40 — filled."** The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | Filled count (fractional rounds). | | `total` | `number` | Capacity = cell count (default 10). | | `rows` | `number \| "auto"` | auto (near-square) or a number; 1 = strip. | | `empty` | `"outline" \| "blank"` | How empty cells render (default outline). | | `unit` | `string` | Noun for the summary (e.g. "seats"). | | `label` | `"none" \| "count" \| "percent"` | Centered readout when the comb has room (default "none"). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Horizon (/docs/charts/horizon) Horizon answers "what happened across this wide-range series — in a 14-pixel row?" The series is cut into bands and folded: layer opacity carries magnitude, so extremes stay visible at heights where a sparkline would flatten into noise. **How to read it** — every band rises from the row's bottom edge, positive or negative; darker means farther from the baseline, not which direction. Above-baseline values shade in the accent color, below-baseline in the negative color, so direction is never color-alone even though both fold upward the same way. ```tsx <Horizon data="[2, 5, 9, 14, 22, 31, 26, 18, 12, 24, 38, 45, 41, 30, 19, 11, 6, 3, 8, 16, 27, 35, 29, 20]" title="Cluster load" width="220" height="22" /> ``` ## Install [#install] ```tsx import { Horizon } from "@microcharts/react/horizon"; <Horizon data={cpuLoad} title="Cluster load" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — dense monitoring rows (dozens stacked), wide-range series in tight cells. * **Avoid for** — first-glance audiences (folding needs a key), or a few rows with room (Sparkline). ## Variants [#variants] ```tsx `" > <Horizon data="[2, 5, 9, 14, 22, 31, 26, 18, 12, 24, 38, 45, 41, 30, 19, 11, 6, 3, 8, 16, 27, 35, 29, 20]" folds="3" title="Three folds" width="220" height="22" /> ``` ```tsx `" > <Horizon data="[18, 22, 19, 25, 31, 20, 17, 24, 29, 21, 19, 26]" baseline="20" title="Latency vs 20 ms SLA" width="220" height="22" /> ``` ```tsx `" > <Horizon data="[ 200, 500, 900, 1400, 2200, 3100, 2600, 1800, 1200, 2400, 3800, 4500, ]" format="{ maximumFractionDigits: 0 }" locale="de-DE" title="Localized cluster load" width="220" height="22" /> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, the accessible summary's range and last-value numbers follow that locale's own grouping ("4.500" in German, not "4,500"). The interactive readout's per-point values localize the same way; the folded geometry never changes. ## Edge cases [#edge-cases] ```tsx `" > <Horizon data="[5, -3, 8, -12, 2, -6, 10]" title="Net flow" width="160" height="22" /> ``` ```tsx `"> <Horizon data="[5, 5, 5, 5, 5]" title="Flat" width="160" height="22" /> ``` Negative values take the negative token and fold from the same bottom edge as positive values (the default `mode="mirror"`) — both directions get darker as they move away from the baseline, so "denser" always means "farther from typical," never "which sign." Identical values across the whole row still render as a solid block rather than vanishing, keeping "flat" visibly distinct from "no data." ## Why this default [#why-this-default] Two folds is the default because it needs no training to read approximately; three folds trade learnability for density and should be reserved for ranges that genuinely span them. The `baseline` is authored, never inferred — a fold origin is a claim about what "normal" means. ## Accessibility [#accessibility] The accessible name reads the unfolded series — **"Trending up 900%. Range 2 to 45. Last value 20."** — so screen-reader users get the true values, not the folded geometry. The interactive readout announces unfolded values per point. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | Series over time. | | `folds` | `2 \| 3` | Band count — 3 only when the range genuinely spans it. | | `mode` | `"mirror" \| "offset"` | Mirror flips negatives upward (denser); offset keeps up/down. | | `baseline` | `number` | Fold origin (e.g. a target level) — authored, never inferred. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Hourglass (/docs/charts/hourglass) Hourglass answers "how much time is gone *and* how much remains?" — the two-sided story a progress bar can't tell. Sand fills the top chamber (remaining) and the bottom (elapsed), and both areas are **area-true**: a naive linear-height fill in a triangular bulb would overstate early progress by up to 2×, so the geometry solves for true proportional area. A thin stream at the neck marks "running"; it disappears at both ends, because finished and not-started are shape-distinct states. ```tsx <span className="inline-flex gap-4 items-center"> <Hourglass value="0.15" height="40" title="15% elapsed" /> <Hourglass value="0.5" height="40" title="half" /> <Hourglass value="0.85" height="40" title="85% elapsed" /> </span> ``` ## Install [#install] ```tsx import { Hourglass } from "@microcharts/react/hourglass"; <Hourglass value={0.75} title="Session" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a deadline or session-expiry read in a sentence, a TTL cell where remaining is the story, or a time-boxed tab or countdown. * **Avoid for** — exact percentages (Progress), trends (Sparkline), or non-time fractions. ## Variants [#variants] ```tsx <Hourglass value={1} />`" > <span className="inline-flex gap-6 items-center"> <Hourglass value="0.7" label="remaining" height="44" /> <Hourglass value="1" height="44" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <Hourglass value="0" title="Not started" height="36" /> ``` ```tsx `"> <Hourglass value="1" title="Finished" height="36" /> ``` ```tsx `" > <Hourglass value="1.4" title="Overrun" height="36" /> ``` ```tsx `"> <Hourglass value="Number.NaN" title="Invalid" height="36" /> ``` ## Why this default [#why-this-default] `value` is the elapsed fraction — the same polarity as `Progress` — so the two compose in one product without re-learning which way is which. The area-true solve is the load-bearing honesty rule: in an inherently nonlinear container, the sand areas are exactly proportional to elapsed and remaining. The stream is a binary state mark, not decoration, and is never animated in the static entry — it simply renders while `0 < value < 1`. ## Accessibility [#accessibility] The accessible name carries both sides — a glyph above reads **"70% elapsed, 30% remaining."** The interactive entry cross-fades the sand levels on change (opacity plus a scale-from-the-floor settle, never a path interpolation) and announces only when the value crosses a documented threshold (50 / 90 / 100%), so a streaming value never spams. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | Elapsed fraction 0–1 (like Progress). | | `stream` | `boolean` | The running-sand cue (default true). | | `label` | `"none" \| "remaining" \| "elapsed"` | Print the percent that matters to the context. | 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](/docs/quickstart#the-shared-grammar). # Hypnogram (/docs/charts/hypnogram) Hypnogram answers "which discrete state was the system in over time, and how choppy were the transitions?". It refuses interpolation — there are no diagonals, ever — because a state is a fact that holds until the next one, not a sample of a continuum a line chart can slope between. ```tsx `" > <Hypnogram data="[ { t: 0, state: "Awake" }, { t: 8, state: "Light" }, { t: 22, state: "Deep" }, { t: 38, state: "Light" }, { t: 50, state: "REM" }, { t: 62, state: "Light" }, { t: 74, state: "Deep" }, { t: 86, state: "Light" }, { t: 98, state: "REM" }, { t: 110, state: "Awake" }, ]" states="["Awake", "REM", "Light", "Deep"]" domain="[0, 120]" title="Sleep stages" width="300" height="64" /> ``` ## Install [#install] ```tsx import { Hypnogram } from "@microcharts/react/hypnogram"; <Hypnogram data={sleep} states={["Awake","REM","Light","Deep"]} title="Sleep stages" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — sleep stages, deploy / machine / incident state over time. * **Avoid for** — continuous signals (Sparkline) or a single current state (StatusDot). ## Variants [#variants] ```tsx `" > <Hypnogram data="[ { t: 0, state: "Awake" }, { t: 30, state: "REM" }, { t: 60, state: "Deep" }, { t: 90, state: "Light" }, ]" states="["Awake", "REM", "Light", "Deep"]" domain="[0, 120]" mode="lanes" title="Lanes" width="260" height="64" /> ``` ```tsx `" > <Hypnogram data="[ { t: 0, state: "Awake" }, { t: 8, state: "Light" }, { t: 22, state: "Deep" }, { t: 38, state: "Light" }, { t: 74, state: "Deep" }, { t: 110, state: "Awake" }, ]" states="["Awake", "REM", "Light", "Deep"]" domain="[0, 120]" emphasis="Deep" title="Deep emphasised" width="260" height="64" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <Hypnogram data="[{ t: 0, state: "Deep" }]" domain="[0, 120]" title="Deep sleep throughout" width="220" height="40" /> ``` ```tsx `" > <Hypnogram data="[ { t: 0, state: "Awake" }, { t: 20, state: "Groggy" }, { t: 40, state: "Light" }, ]" states="["Awake", "Light", "Deep"]" title="Unlisted state appended" width="220" height="52" /> ``` A single entry holds its state across the whole domain — one flat run, and the summary names it directly — **"1 state, no transitions; Deep throughout."** — rather than describing a one-point chart. A state present in the data but missing from an explicit `states` order is never dropped: it's appended as its own row (with a dev-only console warning), so the strip always accounts for every state it's given. ## Why this default [#why-this-default] Right-angle steps with an explicit `states` order are the clinically proven read. Order is meaningful — for ordinal states (sleep depth, incident severity) pass it explicitly; for nominal states with no rank, use `mode="lanes"` so the vertical axis never implies one. Any smoothing or easing of the step corners would be a lie about the data, so the entrance is a left-to-right clip reveal of the finished trace — the steps themselves are never interpolated. ## Accessibility [#accessibility] The accessible name summarises the shape — **"3 transitions across 4 states; longest run Awake."** The interactive entry roves the runs; each announces its state and span (**"Light, from 8 to 22."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ t, state }[]` | State holds from t to the next entry. | | `states` | `string[]` | Row order top→bottom; ordinal semantics live here. | | `emphasis` | `string` | Accents one state — the decision read. | | `mode` | `"steps" \| "lanes"` | Lanes for nominal states with no rank. | | `connectors` | `boolean` | Vertical transition strokes (default true); off for ultra-dense strips. | | `labels` | `boolean` | Left-gutter state names (default: on when width ≥ 96). | | `colors` | `string[]` | Per-state lane colours (lanes mode), cycled; overrides --mc-cat-N. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # IconArray (/docs/charts/icon-array) IconArray answers "how likely is this, really?". A stated rate becomes countable: filled units in a fixed N-unit grid, with the denominator visible. Two moves kill denominator neglect — the ratio label and the fixed grid. Fill order is contiguous reading-order (scattered is harder to count), and there are **no partial-unit fills ever**: a sub-unit rate is flagged, never faked. ```tsx <IconArray value="0.15" total="20" title="Adverse events" width="140" height="30" /> ``` ## Install [#install] ```tsx import { IconArray } from "@microcharts/react/icon-array"; <IconArray value={0.15} total={20} title="Adverse events" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — risk in a sentence, uptake / adoption rates, lay-audience probabilities. * **Avoid for** — a trend (Sparkline) or a full distribution (QuantileDots). ## Variants [#variants] ```tsx <IconArray value={0.15} total={20} positive="down" />`" > <span className="inline-flex flex-col gap-2"> <IconArray value="0.1" total="10" title="1 in 10" width="130" height="28" /> <IconArray value="0.15" total="20" positive="down" title="Risk polarity" width="150" height="28" /> </span> ``` ```tsx <IconArray value={0.6} total={10} shape="round" /> <IconArray value={0.37} total={100} label="none" />`" > <span className="inline-flex flex-col gap-2"> <IconArray value="0.15" total="20" label="percent" title="Percent label" width="110" height="26" /> <IconArray value="0.6" total="10" shape="round" title="Round units" width="130" height="28" /> <IconArray value="0.37" total="100" label="none" title="100-unit grid" width="90" height="90" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <IconArray value="0" total="20" title="No adverse events" width="140" height="30" /> ``` ```tsx `" > <IconArray value="0.01" total="20" title="Rare event" width="140" height="30" /> ``` ```tsx `"> <IconArray value="1" total="20" title="All affected" width="140" height="30" /> ``` A rate of exactly 0 draws every unit hollow. A rate that is real but rounds to 0 whole units (`note: "sub"`) still shows a hollow grid but the summary says so explicitly — never a fractional unit standing in for "almost none." `value` is clamped to `[0, 1]` and non-finite input renders as 0, so a bad upstream number never breaks the grid. ## Why this default [#why-this-default] `total={20}` and `label="ratio"` are the default pairing because "3 in 20" reads faster and more honestly for a lay audience than "15%" — the denominator stays visible instead of being computed in the reader's head. Units fill in reading order from the top-left, never scattered: medical-risk-communication research finds scattered fills measurably harder to count at a glance, and counting is the whole point of this chart. There is no partial-unit fill — a 37% rate is never drawn as a unit that's 37% full, because a sub-pixel sliver of color is a precision claim this chart doesn't make. ## Accessibility [#accessibility] The accessible name states the count and the rate — **"3 in 20. About 15%."** — and degenerate rates say so plainly ("0 in 20", "20 in 20 — all."). The interactive entry roves the grid in reading order with the arrow keys (2-D, row-major) and announces each unit's state plus the running count: **"Unit 1 of 20 — filled. 3 of 20 filled."** The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The rate, 0–1. | | `total` | `10 \| 20 \| 100` | Denominator / grid size (default 20). | | `label` | `"ratio" \| "percent" \| "none"` | "3 in 20" (default) reads better than "15%" for lay audiences. | | `shape` | `"square" \| "round" \| "dot"` | Shared cell vocabulary (default square). | | `positive` | `"up" \| "down"` | Polarity — down (fewer is better) flips the fill to the risk tone. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # All charts (/docs/charts) One grammar runs through all of them: `data` alone always renders something correct, and a prop name means the same thing on every chart. So you don't pick by chart — you pick by the **decision** you need read at a glance. The chooser below is filed exactly that way: start from the question, land on the chart. - [Browse all charts](/charts) ## Static and interactive [#static-and-interactive] Nearly every chart ships two entries — a hook-free **static** default (server-component safe, zero client JavaScript) and an **interactive** twin from a `/interactive` subpath. WindBarb is the lone static-only exception. Every chart page lists the import paths it has; the [Quickstart](/docs/quickstart#add-interactivity) covers when to reach for which, and [Accessibility](/docs/accessibility#one-interaction-contract) documents the one interaction contract they all share. # LikertStrip (/docs/charts/likert-strip) LikertStrip answers "does the response lean agree or disagree — and how hard?" — the valence + balance read that SegmentedBar (unvalenced composition) cannot say. The center line is the question; everything else is the answer. ```tsx <LikertStrip data="[ { label: "Strongly disagree", value: 10 }, { label: "Disagree", value: 14 }, { label: "Neutral", value: 14 }, { label: "Agree", value: 34 }, { label: "Strongly agree", value: 28 }, ]" title="Q1 satisfaction" width="220" height="24" /> ``` ## Install [#install] ```tsx import { LikertStrip } from "@microcharts/react/likert-strip"; <LikertStrip data={[ { label: "Strongly disagree", value: 10 }, { label: "Disagree", value: 14 }, { label: "Neutral", value: 14 }, { label: "Agree", value: 34 }, { label: "Strongly agree", value: 28 }, ]} title="Q1 satisfaction" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — survey question rows (share one scale via SparkGroup), sentiment in cards. * **Avoid for** — more than 7 levels, or exact per-level values (MiniBar). ## Variants [#variants] ```tsx <LikertStrip data={responses} label="net" />`" > <span className="inline-flex flex-col gap-3"> <LikertStrip data="[ { label: "Strongly disagree", value: 10 }, { label: "Disagree", value: 14 }, { label: "Neutral", value: 14 }, { label: "Agree", value: 34 }, { label: "Strongly agree", value: 28 }, ]" neutral="omit" title="Omit neutral" width="220" height="24" /> <LikertStrip data="[ { label: "Strongly disagree", value: 10 }, { label: "Disagree", value: 14 }, { label: "Neutral", value: 14 }, { label: "Agree", value: 34 }, { label: "Strongly agree", value: 28 }, ]" label="net" title="Net score" width="220" height="24" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <LikertStrip data="[ { label: "Disagree", value: 0 }, { label: "Agree", value: 0 }, ]" title="No responses" width="160" height="20" /> ``` ```tsx `" > <LikertStrip data="[ { label: "Disagree", value: 0 }, { label: "Neutral", value: 10 }, { label: "Agree", value: 0 }, ]" title="All neutral" width="160" height="20" /> ``` Empty data, or data whose values all resolve to 0, has nothing to divide into a diverging read — no bar draws, and the accessible name says so plainly: **"No responses."** When every non-zero response lands on the neutral level, the bar is entirely the center segment and the summary reads **"All responses neutral."** instead of forcing a lean out of no signal. Negative counts are treated as 0 rather than pushed the wrong direction across the center line — a chart that lies about which side a count is on is worse than one that drops it — and the static entry logs a dev warning when it happens. ## Why this default [#why-this-default] Both neutral conventions are supported honestly: `split` straddles the center (the canonical placement), `omit` removes neutral from the bar for cleaner pole comparison — but its share is ALWAYS still counted in the total and spoken in the accessible summary; neutral is never silently dropped. Graded opacity encodes ordinal distance from neutral, never magnitude. ## Accessibility [#accessibility] The accessible name is the full valence read — **"62% agree, 24% disagree, 14% neutral. Leans positive."** A |net| under 5 points reads "Balanced." The interactive entry steps levels in data order (**"Disagree: 14%, level 2 of 5."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value }[]` | Ordinal levels, negative → positive. | | `neutral` | `"split" \| "omit"` | Center-straddle or omit-from-bar (always labeled). | | `label` | `"ends" \| "net" \| "none"` | Agree/disagree % or one signed score. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # MicroBox (/docs/charts/micro-box) MicroBox answers "what are the p50 and spread of this metric?" — the five-number summary in a table row. Min-max whiskers by default (Tukey fences imply a normality assumption most product data doesn't meet); `tukey` mode exposes fence-breakers as dots. ```tsx <MicroBox stats="{ min: 12, q1: 35, median: 42, q3: 51, max: 96 }" title="p95 latency" width="220" height="32" /> ``` ## Install [#install] ```tsx import { MicroBox } from "@microcharts/react/micro-box"; <MicroBox stats={{ min: 12, q1: 35, median: 42, q3: 51, max: 96 }} title="p95 latency" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — latency percentile rows (p50/p95/p99), spread beside a stat — precomputed `stats` is the production path. * **Avoid for** — distribution shape (HistogramStrip) or fewer than 5 observations (renders honest dots). ## Variants [#variants] ```tsx 40 + i), 400, 500]; <MicroBox data={values} whiskers="tukey" />`" > <MicroBox data="[...Array.from({ length: 20 }, (_, i) => 40 + i), 400, 500]" whiskers="tukey" title="With outliers" style="{ width: 220, height: 32 }" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <MicroBox data="[3, 7, 9]" title="Only three" width="220" height="32" /> ``` ```tsx `" > <MicroBox data="[7, 7, 7, 7, 7, 7]" title="All equal" width="220" height="32" /> ``` ## Why this default [#why-this-default] Never a box from fewer than 5 observations — dots at the raw values instead. Precomputed `stats` with non-monotonic values are refused with a dev warning: garbage in must not render a plausible-looking lie. Outlier dots cap at 3 per side (the furthest). ## Accessibility [#accessibility] The accessible name is the five-number reading — **"Median 50.5, middle half 45.25 to 55.75, range 40 to 500."** The interactive entry roves a fixed 5-stop model (min → Q1 → median → Q3 → max), announcing each stat (**"Median: 42."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` | `number[]` | Raw observations (exclusive with stats). | | `stats` | `{ min; q1; median; q3; max }` | Precomputed server aggregates. | | `whiskers` | `"minmax" \| "tukey"` | Tukey exposes outliers as dots. | | `outliers` | `boolean` | Render outlier dots in tukey mode. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # MicroDonut (/docs/charts/micro-donut) MicroDonut answers "roughly what is this made of?" at icon size — an honest, capped concession to a ubiquitous demand. For any comparative read, use [SegmentedBar](/docs/charts/segmented-bar): a flat bar beats a donut of the same data at every size we ship. The wedge cap and labeled rollup are non-optional. ```tsx <MicroDonut data="[ { label: "Chrome", value: 620 }, { label: "Safari", value: 240 }, { label: "Firefox", value: 90 }, { label: "Edge", value: 30 }, { label: "Arc", value: 20 }, ]" size="48" title="Traffic mix" style="{ width: 72, height: 72 }" /> ``` ## Install [#install] ```tsx import { MicroDonut } from "@microcharts/react/micro-donut"; <MicroDonut data={mix} title="Traffic mix" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a mix icon beside the printed headline number in a KPI card. * **Avoid for** — any comparative read (SegmentedBar) — the docs steer there first. ## Variants [#variants] ```tsx 62% Chrome <MicroDonut data={mix} decorative /></span>`" > <span className="text-lg"> {"62% Chrome "} <MicroDonut data="[ { label: "Chrome", value: 620 }, { label: "Safari", value: 240 }, { label: "Firefox", value: 140 }, ]" style="{ width: "1em", height: "1em" }" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <MicroDonut data="[{ label: "Chrome", value: 620 }]" title="All Chrome" size="40" style="{ width: 40, height: 40 }" /> ``` ```tsx `"> <MicroDonut data="[]" title="Empty" size="40" style="{ width: 40, height: 40 }" /> ``` ## Why this default [#why-this-default] The hole is mandatory — the donut's angle + arc-length double encoding beats the pie's area read, which is why pie stays unshipped. Never exploded, tilted, or shadowed. A single category renders a full annulus that looks like a 100% ProgressRing — the summary disambiguates. ## Accessibility [#accessibility] The accessible name is the full composition (same wording as SegmentedBar). `decorative` marks the chart aria-hidden for the one sanctioned ornamental use — beside a printed value — and the interactive entry refuses to make a decorative donut a tab stop. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value }[]` | Parts of the whole. | | `maxWedges` | `number` | Rollup threshold (default 4). | | `decorative` | `boolean` | Redundant ornament beside a printed value → aria-hidden. | | `weight` | `number` | Annulus thickness (shared with ProgressRing). | | `label` | `"none" \| "total"` | Center total when the hole has room (default "none"). | | `colors` | `string[]` | Per-wedge colours, cycled; overrides --mc-cat-N. Other stays neutral. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # MicroScatter (/docs/charts/micro-scatter) MicroScatter answers "are these two variables related?" — the relationship story no other micro chart tells. Dots render at 75% opacity so overplot reads as density instead of lying by occlusion, and duplicates are never jittered: position is the encoding. ```tsx <span className="text-lg"> {"Latency and error rate "} <MicroScatter data="Array.from({ length: 24 }, (_, i) => ({ x: i, y: i * 3 + ((i * 7) % 5) * 6 }))" title="Latency vs error rate" style="{ width: "3em", height: "1.8em" }" /> {" correlate strongly."} </span> ``` ## Install [#install] ```tsx import { MicroScatter } from "@microcharts/react/micro-scatter"; <MicroScatter data={pairs} title="Latency vs error rate" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — correlation in a sentence, two-metric relationships in KPI cards. * **Avoid for** — more than 60 points (bin instead) or ordered time series (Sparkline). ## Variants [#variants] ```tsx `" > <MicroScatter data="Array.from({ length: 24 }, (_, i) => ({ x: i, y: i * 3 + ((i * 7) % 5) * 6 }))" title="With trend" style="{ width: 140, height: 84 }" /> ``` ```tsx `"> <MicroScatter data="Array.from({ length: 24 }, (_, i) => ({ x: i, y: i * 3 + ((i * 7) % 5) * 6 }))" focal="12" title="You are here" style="{ width: 140, height: 84 }" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <MicroScatter data="[]" title="No pairs" style="{ width: 100, height: 60 }" /> ``` ```tsx `"> <MicroScatter data="[ { x: 1, y: 2 }, { x: 2, y: 3 }, ]" title="Two points" style="{ width: 100, height: 60 }" /> ``` ```tsx `"> <MicroScatter data="[ { x: 5, y: 5 }, { x: 5, y: 5 }, { x: 1, y: 8 }, ]" title="Overlapping pair" style="{ width: 100, height: 60 }" /> ``` Empty data draws just the frame with "No data." as the summary. Under 3 points (or a zero-variance cloud) states the count and stops — no correlation claim without enough evidence to back it. Coincident points are never jittered apart: they overlap exactly, and at 75% dot opacity the overlap itself reads as extra density rather than hiding a point. ## Why this default [#why-this-default] Axes are unlabeled at this scale, so `title` must name both variables, the way the hero demo above does. The summary's relationship words are a documented heuristic on |r| (≥ 0.7 strong, ≥ 0.4 moderate, ≥ 0.2 weak), and whenever a relationship word appears, r appears beside it: claim and evidence travel together. Fewer than 3 points, or a zero-variance cloud, makes no claim at all. ## Accessibility [#accessibility] The accessible name is the count plus the evidence-backed relationship — **"24 points. Strong positive relationship (r 0.93)."** — or just **"2 points."** when no claim is honest. The interactive entry steps points ordered by x and announces each formatted pair. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ x; y }[]` | Unordered pairs. | | `trend` | `boolean` | Least-squares line — linear only, never smoothed. | | `focal` | `number` | Accent one point — "this one, among all of them". | | `xDomain` | `[number, number]` | X scale (domain keeps its grammar meaning: y). | | `domain` | `[number, number]` | Y scale — the shared grammar name, paired with xDomain. | | `r` | `number` | Dot radius, clamped [1, 3]. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # MiniBar (/docs/charts/mini-bar) MiniBar answers "which category is biggest, and by roughly how much?". Bars are always zero-anchored, and the data's own order is the default truth — weekday order or funnel order carries meaning that ranking would destroy, so `order` is explicit, never silent. ```tsx <MiniBar data="[ { label: "East", value: 940 }, { label: "West", value: 410 }, { label: "South", value: 620 }, { label: "North", value: 120 }, ]" title="Sales by region" width="150" height="48" /> ``` ## Install [#install] ```tsx import { MiniBar } from "@microcharts/react/mini-bar"; <MiniBar data={regions} title="Sales by region" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — per-row category mix in tables, small comparisons in KPI cards. * **Avoid for** — more than 8 categories (a full bar chart) or time series (SparkBar). ## Variants [#variants] ```tsx <MiniBar data={regions} highlight="South" />`" > <span className="inline-flex gap-6"> <MiniBar data="[ { label: "East", value: 940 }, { label: "West", value: 410 }, { label: "South", value: 620 }, { label: "North", value: 120 }, ]" order="desc" title="Ranked" width="120" height="36" /> <MiniBar data="[ { label: "East", value: 940 }, { label: "West", value: 410 }, { label: "South", value: 620 }, { label: "North", value: 120 }, ]" highlight="South" title="This row's category" width="120" height="36" /> </span> ``` ```tsx `" > <MiniBar data="[ { label: "Mon", value: 4 }, { label: "Tue", value: -2 }, { label: "Wed", value: 6 }, { label: "Thu", value: -1 }, { label: "Fri", value: 3 }, ]" positive="up" title="Daily delta" width="120" height="36" /> ``` ```tsx `" > <MiniBar data="[ { label: "East", value: 12400 }, { label: "West", value: 8600 }, ]" locale="de-DE" title="Localized values" width="80" height="36" /> ``` The extremes named in the summary follow `format`/`locale` — 12400 reads "12.400" under `de-DE` rather than the English "12,400". ## Edge cases [#edge-cases] ```tsx `" > <MiniBar data="[ { label: "a", value: 5 }, { label: "b", value: null }, { label: "c", value: 7 }, ]" title="Gap preserved" width="120" height="36" /> ``` ```tsx `"> <MiniBar data="[{ label: "Only", value: 4 }]" title="Single" width="80" height="36" /> ``` A `null` value draws no bar but keeps its band, so the two real bars around it stay exactly as far apart as a fully populated row — alignment across a column of MiniBars survives missing data. A single category still renders and its summary says so plainly ("1 category…") rather than degenerating into a bare-bar special case. Past 8 categories the component still renders every bar (nothing is dropped or truncated) but logs a dev warning — MiniBar is a cell chart, and a wider comparison belongs in a full bar chart. ## Why this default [#why-this-default] Unsorted by default: the data's order often IS information. Null values keep their slot as a gap, so a missing category never shifts its neighbors. Explicit domains are widened to include zero — a bar whose length doesn't start at zero is a lie, so the component refuses to draw one. ## Accessibility [#accessibility] The accessible name carries count and extremes — **"4 categories. Highest East 940, lowest North 120."** The interactive entry announces each bar with its rank: **"East: 940 — 1st of 4."** The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value }[]` | Categories in meaningful order. | | `order` | `"data" \| "desc" \| "asc"` | Ranking read vs positional read — data-facing, not styling. | | `highlight` | `number \| string` | Index or label to emphasize. | | `orientation` | `"horizontal" \| "vertical"` | Rows for wider, shorter cells. | | `positive` | `"up" \| "down"` | Engages pos/neg tokens on signed data. | | `label` | `"none" \| "max"` | Peak-value readout (vertical only; default "none"). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # MinimapStrip (/docs/charts/minimap-strip) MinimapStrip answers "where am I in the whole — and where in the whole is everything else I care about?". A content thumbnail sits under a viewport window and a lane of annotation ticks, and any region you haven't loaded or crawled is drawn as fog rather than blank — because absence is not the same as zero. The unknown share travels with the accessible name. ```tsx <MinimapStrip data="{ content: Array.from({ length: 1200 }, (_, i) => Math.abs(Math.sin(i / 40)) + Math.abs(Math.sin(i / 150)) * 0.6), window: [520, 660], marks: [100, 600, 1100], known: [[0, 1104]], }" title="Document position" width="300" height="18" /> ``` ## Install [#install] ```tsx import { MinimapStrip } from "@microcharts/react/minimap-strip"; <MinimapStrip data={{ content: Array.from( { length: 1200 }, (_, i) => Math.abs(Math.sin(i / 40)) + Math.abs(Math.sin(i / 150)) * 0.6, ), window: [520, 660], marks: [100, 600, 1100], known: [[0, 1104]], }} title="Document position" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — document or log position, long-timeline navigation. * **Avoid for** — a single value (Progress) or exact content values (Sparkline). ## Variants [#variants] ```tsx Math.abs(Math.sin(i / 40)) + Math.abs(Math.sin(i / 150)) * 0.6, ), window: [300, 440], marks: [600, 1000], }} mode="heat" />`" > <MinimapStrip data="{ content: Array.from({ length: 1200 }, (_, i) => Math.abs(Math.sin(i / 40)) + Math.abs(Math.sin(i / 150)) * 0.6), window: [300, 440], marks: [600, 1000], }" mode="heat" title="Heat" width="300" height="18" /> ``` ## Edge cases [#edge-cases] ```tsx Math.abs(Math.sin(i / 20))), window: [40, 90], known: [[0, 200]], }} />`" > <MinimapStrip data="{ content: Array.from({ length: 200 }, (_, i) => Math.abs(Math.sin(i / 20))), window: [40, 90], known: [[0, 200]], }" title="Fully known" width="220" height="16" /> ``` ## Why this default [#why-this-default] Bars plus a separate mark lane keep "where am I" and "where are the annotations" as two clean reads instead of one muddle. Fog-of-war is a first-class state — unknown regions get a hatched texture, never a blank stretch that would read as empty content, and the unknown share is disclosed in the summary. The window maps linearly to the domain; there is no fisheye to distort where you are. ## Accessibility [#accessibility] The accessible name places you in the whole — **"Viewing 12% of the whole (300–440 of 1,200); 2 marks."** The interactive entry is a slider: drag or click to move the window, or nudge it with ←/→ (Shift for a bigger jump). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ content, window, marks?, known? }` | Density series, viewport, ticks, covered regions. | | `mode` | `"bars" \| "heat"` | Heat is a calmer opacity strip. | | `markLane` | `boolean` | Dedicated tick lane vs overlaying ticks. | | `onWindowChange` | `(window: [number, number]) => void` | (interactive) Fires with the new `[start, end]` index range as the brush window is dragged. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # MoonPhase (/docs/charts/moon-phase) MoonPhase answers "how far through the cycle or period are we?" with a form almost everyone reads without a legend: the illuminated fraction of a disc. The lit **area** equals the value exactly — a closed-form terminator, not the phase-angle approximation that under-lights mid-cycle — so 50% genuinely lights half the disc. Progress mode fills monotonically; cycle mode maps the real lunar sequence. ```tsx <span className="inline-flex gap-3 items-center"> <MoonPhase value="0.1" size="24" title="10%" /> <MoonPhase value="0.35" size="24" title="35%" /> <MoonPhase value="0.5" size="24" title="50%" /> <MoonPhase value="0.75" size="24" title="75%" /> <MoonPhase value="1" size="24" title="full" /> </span> ``` ## Install [#install] ```tsx import { MoonPhase } from "@microcharts/react/moon-phase"; <MoonPhase value={0.68} title="Sprint" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — sprint or quota progress in a sentence, a billing-period or release-cycle marker, or any 0–1 completion that reads at a glance. * **Avoid for** — exact percentages (Progress), trends (Sparkline), or comparisons (MiniBar). ## Variants [#variants] ```tsx // first quarter <MoonPhase value={0.5} mode="cycle" /> // full moon`" > <span className="inline-flex gap-3 items-center"> <MoonPhase value="0" mode="cycle" size="24" title="new" /> <MoonPhase value="0.25" mode="cycle" size="24" title="first quarter" /> <MoonPhase value="0.5" mode="cycle" size="24" title="full" /> <MoonPhase value="0.75" mode="cycle" size="24" title="last quarter" /> </span> ``` ## Edge cases [#edge-cases] ```tsx // clamps to 0 — new, dark disc <MoonPhase value={1.6} title="Above one" /> // clamps to 1 — full, lit disc`" > <span className="inline-flex gap-3 items-center"> <MoonPhase value="-0.4" size="28" title="Below zero" /> <MoonPhase value="1.6" size="28" title="Above one" /> </span> ``` ## Why this default [#why-this-default] Progress mode is the default because period-progress is the common need — a sprint or quota filling from new to full, monotonically. Pretending the real lunar cycle is monotonic would lie (it waxes then wanes), so `mode="cycle"` is a separate, explicit data-semantic switch, not a preset. The lit area is always exactly the value via the closed form — never the phase-angle shortcut. Area is a medium-precision channel, so steer exact reads to `Progress`; MoonPhase is for the glance. ## Accessibility [#accessibility] The accessible name states the fraction — **"0% of the cycle complete."** in progress mode, or "0% through the cycle." in cycle mode. The interactive entry fades the lit region back in on change with a slight bloom (opacity plus a small scale, never a path interpolation, and skipped entirely under `prefers-reduced-motion`), reveals the exact percent on hover or focus, and announces changes through a polite live region throttled to at most once a second. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | Fraction 0–1 (clamped). | | `mode` | `"progress" \| "cycle"` | progress = monotonic fill; cycle = true lunar mapping (0 new → 0.5 full → 1 new). | 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](/docs/quickstart#the-shared-grammar). # MusicStaff (/docs/charts/music-staff) MusicStaff answers "what's the shape of this short series?" by reading it as a melody: each value is a note, its **pitch** (vertical position on a five-line staff) is the value, and left-to-right is time. Pitch is the only channel — there are no clefs, stems, beams, or bar lines, because every other notation convention would be decoration. The read is in steps (nine to thirteen positions), so exact values steer to `Sparkline` with a label. ```tsx `" > <MusicStaff data="[3, 5, 4, 8, 6, 9, 7, 11]" label="last" title="Sprint melody" width="120" height="26" /> ``` ## Install [#install] ```tsx import { MusicStaff } from "@microcharts/react/music-staff"; <MusicStaff data={weeks} title="Sprint melody" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a weekly-rhythm read in a sentence, the shape of a sprint or short series in a cell, or a per-channel melody in a tab. * **Avoid for** — exact values (Sparkline with a label), long series (over sixteen points), or trends where the exact slope matters. ## Variants [#variants] ```tsx <MusicStaff data={[3, 5, null, 8, 6]} />`" > <span className="inline-flex gap-6 items-center"> <MusicStaff data="[3, 5, 4, 8, 6, 9]" mode="staff" width="100" height="24" /> <MusicStaff data="[3, 5, null, 8, 6]" width="90" height="24" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <MusicStaff data="[7]" title="One value" width="60" height="24" /> ``` ```tsx `" > <MusicStaff data="[null, null, null]" title="No notes" width="80" height="24" /> ``` ```tsx `"> <MusicStaff data="[3000, 5200, 4100, 8300, 6400]" label="last" locale="de-DE" title="Localized last value" width="110" height="24" /> ``` A single value draws one note and no contour line — a melody needs at least two notes to have a shape. An all-`null` series draws the bare staff with no notes at all; the accessible name falls back to `describeSeries`'s own no-data phrasing. With a `locale`, the trailing `label="last"` value follows that locale's own grouping and decimal marks. ## Why this default [#why-this-default] The ledger mode is the default because clipping pitch silently is worse than two extra hairline ledger ticks — a note above or below the staff still reads truly. `mode="staff"` exists for dense cells where ledger lines would collide with a neighbour; there, out-of-range pitches clamp to the nearest staff line or space instead, trading visual precision for a collision-free cell — the accessible summary is unaffected either way, since it describes the raw values, not the clamped pixel positions. Two adjacent equal values are spaced by the time axis, never dodged vertically, because moving a note vertically would change its pitch — and pitch is the data. ## Accessibility [#accessibility] MusicStaff reuses the same natural-language summary as `Sparkline`, verbatim — for `[3, 5, 4, 8, 6, 9]`, **"Trending up 200%. Range 3 to 9. Last value 9."** The interactive entry steps the notes with ←/→, announcing each as **"Point 3 of 6: 4."** The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | The series; null = a rest. | | `mode` | `"staff" \| "ledger"` | ledger (±2, default) or staff (clamp on-staff). | | `label` | `"none" \| "last"` | Print the final value after the last note. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # NetFlow (/docs/charts/net-flow) NetFlow answers "in versus out — and where does that leave us net?". Inflow is an area above a zero baseline, outflow is mirrored below it on **one shared magnitude scale** (never independently scaled to balance the picture), and the net line (`in − out`) rides on top to restore the precise decision value. Gross and net answer different questions; the cell answers both. ```tsx <NetFlow data="[ { in: 42, out: 31 }, { in: 38, out: 35 }, { in: 45, out: 29 }, { in: 40, out: 44 }, { in: 52, out: 38 }, { in: 48, out: 41 }, { in: 55, out: 36 }, { in: 50, out: 47 }, { in: 58, out: 39 }, { in: 44, out: 52 }, { in: 60, out: 41 }, { in: 57, out: 43 }, ]" format="(n) => `${n}k`" label="last" title="Monthly cash flow" width="260" height="30" /> ``` ## Install [#install] ```tsx import { NetFlow } from "@microcharts/react/net-flow"; <NetFlow data={months} title="Monthly cash flow" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — cash flow per account row, in vs out (signups vs churn) in a KPI card, any in-vs-out where the net is the decision. * **Avoid for** — a single net series (Sparkline) or one period's split (Delta / SegmentedBar). ## Variants [#variants] ```tsx <NetFlow data={months} positive="down" />`" > <span className="inline-flex flex-col gap-1.5"> <NetFlow data="[ { in: 45, out: 29 }, { in: 40, out: 44 }, { in: 52, out: 38 }, { in: 44, out: 52 }, { in: 60, out: 41 }, { in: 57, out: 43 }, ]" mode="bars" title="Mirrored bars" width="220" height="28" /> <NetFlow data="[ { in: 45, out: 29 }, { in: 40, out: 44 }, { in: 52, out: 38 }, { in: 44, out: 52 }, { in: 60, out: 41 }, { in: 57, out: 43 }, ]" positive="down" title="Outflow is the goal" width="220" height="28" /> </span> ``` ```tsx `" > <NetFlow data="[ { in: 42000, out: 31000 }, { in: 38000, out: 35000 }, ]" locale="de-DE" title="Localized flow" width="140" height="26" /> ``` The net label and accessible summary both follow `format`/`locale` — 38000 reads "38.000" under `de-DE` rather than the English "38,000". ## Edge cases [#edge-cases] ```tsx `" > <NetFlow data="[{ in: 40, out: 25 }]" title="This month" width="140" height="28" /> ``` ```tsx `" > <NetFlow data="[{ in: -5, out: -3 }]" title="Bad reading" width="140" height="28" /> ``` A single period always renders as mirrored bars, never an area — an area drawn through one point would imply continuity the data doesn't have. `in`/`out` are magnitudes: a negative value is invalid input, not a reversed direction, so it's coerced to `0`. When every period's magnitudes are zero (all periods coerced or genuinely empty), NetFlow draws only the zero baseline — no areas, no bars, no net line — and the accessible name says so plainly: **"No flow across 1 period."** ## Why this default [#why-this-default] Mirrored areas plus a net line, because gross and net answer different questions and a cell must answer both. Both directions share **one** scale — never independently scaled to make the picture look balanced — and both areas anchor at zero, so their extents are honest. The net line is a plain `in − out`, never smoothed, and its sign is stated in the label's **text** so direction is never carried by color alone. ## Accessibility [#accessibility] The accessible name pairs the net with its gross and counts the healthy periods — **"Net +14 last period; in 57 vs out 43; net positive 4 of 6 periods."**. The interactive entry steps the periods and announces inflow, outflow, and the signed net together. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ in; out }[]` | Periods, oldest first — inflow and outflow magnitudes (both ≥ 0). | | `mode` | `"area" \| "bars"` | Mirrored areas (default) or discrete columns for few periods. | | `net` | `boolean` | The net line (in − out). Default true. | | `positive` | `"up" \| "down"` | Which direction is good — 'down' for debt-paydown contexts. | | `label` | `"last" \| "none"` | Signed net in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Ohlc (/docs/charts/ohlc) Ohlc answers "what was the price action per period?" — open, high, low, close, in a cell. Direction is encoded by valence color AND body geometry, never color alone. ```tsx `" > <Ohlc data="Array.from({ length: 20 }, (_, i) => { const base = 140 + Math.sin(i / 3) * 8 + i * 0.6; return { open: Math.round(base * 10) / 10, high: Math.round((base + 3 + (i % 3)) * 10) / 10, low: Math.round((base - 3 - (i % 2)) * 10) / 10, close: Math.round((base + (i % 2 === 0 ? 2 : -1.5)) * 10) / 10, }; })" title="ACME 20 sessions" width="240" height="30" /> ``` ## Install [#install] ```tsx import { Ohlc } from "@microcharts/react/ohlc"; <Ohlc data={sessions} title="ACME sessions" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — watchlist table rows, ticker KPI cards. * **Avoid for** — a single close series (Sparkline), or more than \~20 periods. ## Variants [#variants] ```tsx <Ohlc data={sessions} label="last" />`" > <span className="inline-flex flex-col gap-3"> <Ohlc data="Array.from({ length: 20 }, (_, i) => { const base = 140 + Math.sin(i / 3) * 8 + i * 0.6; return { open: Math.round(base * 10) / 10, high: Math.round((base + 3 + (i % 3)) * 10) / 10, low: Math.round((base - 3 - (i % 2)) * 10) / 10, close: Math.round((base + (i % 2 === 0 ? 2 : -1.5)) * 10) / 10, }; })" mode="bars" title="Bar form" width="240" height="30" /> <Ohlc data="Array.from({ length: 20 }, (_, i) => { const base = 140 + Math.sin(i / 3) * 8 + i * 0.6; return { open: Math.round(base * 10) / 10, high: Math.round((base + 3 + (i % 3)) * 10) / 10, low: Math.round((base - 3 - (i % 2)) * 10) / 10, close: Math.round((base + (i % 2 === 0 ? 2 : -1.5)) * 10) / 10, }; })" label="last" title="With last close" width="260" height="30" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <Ohlc data="[ { open: 100, high: 103, low: 98, close: 102 }, { open: 102, high: 104, low: 99, close: 102 }, { open: 102, high: 105, low: 100, close: 101 }, ]" title="Doji in the middle" width="120" height="26" /> ``` ```tsx `"> <Ohlc data="[{ open: 100, high: 104, low: 97, close: 103 }]" title="Single period" width="60" height="26" /> ``` ## Why this default [#why-this-default] `maxPeriods` renders the most recent N sessions and warns in development past it — data is truncated visibly, never averaged into fake candles. Bodies keep a minimum 1-unit height so doji sessions stay visible. ## Accessibility [#accessibility] The accessible name is the run read — **"20 periods. Last close 150.3, up 7.4%; range 136.4 to 156."** The interactive entry announces each session's four prices (**"Period 18 of 20: open 145.6, high 150.6, low 141.6, close 144.1."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ open; high; low; close }[]` | Periods, oldest first. | | `mode` | `"candle" \| "bars"` | Candle bodies or open/close ticks. | | `maxPeriods` | `number` | Renders the most recent N (never averaged). | | `label` | `"last" \| "none"` | Last close in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # OrbitStatus (/docs/charts/orbit-status) OrbitStatus answers "how slow and how busy is this dependency right now?" in one small mark. The orbit radius is latency — a wider orbit is a slower service — and the orbit's dash density is the call rate, denser dashes meaning more calls. In the interactive entry the satellite orbits at a speed that mirrors that rate, so a busy service visibly spins faster. Both channels are deliberately low-precision ambient reads; for exact numbers, use a `Sparkline` for latency and a `Delta` or `MiniBar` for rate. ```tsx <OrbitStatus latency="240" rate="12" latencyDomain="[0, 500]" rateDomain="[0, 20]" title="Payments API" size="40" /> ``` ## Install [#install] ```tsx import { OrbitStatus } from "@microcharts/react/orbit-status"; <OrbitStatus latency={240} rate={12} latencyDomain={[0, 500]} rateDomain={[0, 20]} title="Payments API" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## Motion, and reduced motion [#motion-and-reduced-motion] The satellite's angular speed is quantized to the same five steps as the static dash density, so the motion and the still frame decode identically — you learn nothing extra from watching, you just feel the rate. This is the deliberate idle-loop exception, allowed because the loop rate is the datum. It pauses off-screen and, under `prefers-reduced-motion`, does not spin at all: the dash density already carries the rate. The satellite's angular *position* never means anything — only its speed does — so the docs say plainly not to read the angle. ## When to use it [#when-to-use-it] * **Good for** — a live dependency health dot in a service table, latency and rate together in one small mark, or an infra status glance. * **Avoid for** — exact latency (`Sparkline`), exact rate (`Delta`, `MiniBar`), or a trend over time (`Sparkline`). ## Sizing [#sizing] One `size` prop, in viewBox units, sets the orbit box — it defaults to `20`. There is no separate `width`/`height`: the glyph is square, and the rendered box widens only by the gutter a `label` reserves. `fontSize` follows `size` unless you set it. ## Variants [#variants] ```tsx <OrbitStatus latency={100} rate={0} latencyDomain={[0, 500]} rateDomain={[0, 20]} />`" > <span className="inline-flex gap-6 items-center"> <OrbitStatus latency="340" rate="8" threshold="300" latencyDomain="[0, 500]" rateDomain="[0, 20]" size="40" summary="false" /> <OrbitStatus latency="100" rate="0" latencyDomain="[0, 500]" rateDomain="[0, 20]" size="40" summary="false" /> </span> ``` ```tsx `" > <OrbitStatus latency="1240" rate="12" latencyDomain="[0, 2000]" rateDomain="[0, 20]" label="latency" locale="de-DE" title="Localized latency" size="40" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <OrbitStatus latency="NaN" rate="5" title="Unreachable" size="40" /> ``` ```tsx `"> <OrbitStatus latency="90" rate="0" latencyDomain="[0, 500]" rateDomain="[0, 20]" size="40" /> ``` ## Why this default [#why-this-default] The dash-density static encoding exists because a paused satellite says nothing — the still frame had to carry both variables or the chart would fail the survivor test, so rate lives in the dashes as well as the spin. The rate is quantized to five ordinal steps in both renderings — five dash counts and five angular periods — and radius and speed always come from the same domains in the static and interactive frames, so nothing drifts. A lone orbit radius is meaningless, so the docs insist on explicit `latencyDomain` and `rateDomain` — the same steer as `FatDigits`. At `threshold`, the satellite doubles and flags the summary, never relying on color alone. Unknown latency or rate goes gray and stops the spin: an unknown dependency must not look healthy. ## Accessibility [#accessibility] The accessible name is both variables with units — **"240ms latency at 12 calls/s."** — plus "— above threshold" when the latency crosses `threshold`, or **"Latency unknown."** when a value is missing. The threshold state is carried by the satellite's size and the summary, never color alone; motion is gated on `prefers-reduced-motion`; and the live region announces threshold crossings only. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `latency` (required) | `number` | Orbit radius (weak — pass a domain). | | `rate` (required) | `number` | Dash density / satellite speed. | | `latencyDomain` | `[number, number]` | Latency extent (insist on it — a lone radius is meaningless). | | `rateDomain` | `[number, number]` | Rate extent (default [0, 2·rate]). | | `threshold` | `number` | Latency threshold: at/above it the satellite doubles + the summary flags it. | 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](/docs/quickstart#the-shared-grammar). # PairedBars (/docs/charts/paired-bars) PairedBars answers "how does actual compare to expected, category by category?". Value and reference always share one zero-anchored domain — comparing bars on different scales is the cardinal grouped-bar lie — and the reference is muted by two structural cues (opacity *and* width), never color alone. ```tsx `" > <PairedBars data="[ { label: "East", value: 940, ref: 1200 }, { label: "West", value: 410, ref: 400 }, { label: "South", value: 620, ref: 600 }, { label: "North", value: 120, ref: 300 }, ]" title="Actual vs plan" width="200" height="64" /> ``` ## Install [#install] ```tsx import { PairedBars } from "@microcharts/react/paired-bars"; <PairedBars data={regions} title="Actual vs plan" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — budget vs actual per region, target vs result rows. * **Avoid for** — data without a reference series (MiniBar) or more than 5 pairs. ## Variants [#variants] ```tsx `" > <PairedBars data="[ { label: "East", value: 940, ref: 1200 }, { label: "West", value: 410, ref: 400 }, ]" mode="overlay" title="Overlay" width="140" height="44" /> ``` ```tsx `" > <PairedBars data="[ { label: "East", value: 940, ref: 1200 }, { label: "West", value: 410, ref: 400 }, ]" positive="up" title="Over/under plan" width="140" height="44" /> ``` ```tsx `" > <PairedBars data="[{ label: "East", value: 9400, ref: 12000 }]" locale="de-DE" title="Localized" width="80" height="44" /> ``` The gap named in the summary follows `format`/`locale` — 12000 reads "12.000" under `de-DE` rather than the English "12,000". ## Edge cases [#edge-cases] ```tsx `" > <PairedBars data="[{ label: "East", value: 940, ref: null }]" title="No plan yet" width="100" height="44" /> ``` ```tsx `"> <PairedBars data="[{ label: "East", value: 940, ref: 1200 }]" title="Single pair" width="80" height="44" /> ``` A pair whose `ref` is `null` draws its value bar alone — no ghost, no zero-width placeholder — and the interactive entry announces it as **"East: 940, no reference."** rather than pretending a comparison exists. Past 5 pairs the grouped read blurs into noise, so the component still renders every pair but logs a dev warning. ## Why this default [#why-this-default] Grouped over overlay by default — overlap hides small over-shoots, so the denser overlay form is the variant you choose for tight cells, not the analytical default. A pair with a missing reference renders the value bar alone and announces "no reference"; a chart where *every* reference is missing dev-warns and steers to MiniBar. ## Accessibility [#accessibility] The accessible name leads with the largest gap — **"2 pairs. Largest gap East: 940 vs 1,200."** The interactive entry roves pairs and announces each as value vs reference (**"East: 940 vs 1,200."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value; ref }[]` | Value + reference per category. | | `mode` | `"grouped" \| "overlay"` | Overlay puts the ref as a full-width ghost behind — halves the footprint. | | `positive` | `"up" \| "down"` | Over/under-reference valence tint. | | `orientation` | `"horizontal" \| "vertical"` | Rows for wide cells. | | `locale` | `string \| string[]` | BCP 47 locale(s) for the gap named in the summary, e.g. "de-DE". | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # ParetoStrip (/docs/charts/pareto-strip) ParetoStrip answers "what should we fix first?". It sorts the categories descending and overlays a **cumulative-share line on a fixed 0–100% scale** that spans the full height and is never rescaled to steepen the curve. The bars up to the threshold crossing are accent — the **vital few** — and the rest are muted, because the chart's one job is to say where to stop reading. 80% is a working reference, not a law, and `Other` never re-enters the ranking. ```tsx <ParetoStrip data="[ { label: "Timeouts", value: 38 }, { label: "OOM", value: 24 }, { label: "Deploy", value: 15 }, { label: "Config", value: 9 }, { label: "Network", value: 7 }, { label: "Auth", value: 4 }, { label: "Disk", value: 3 }, { label: "DNS", value: 3 }, { label: "Other bug", value: 2 }, ]" unit="causes" metric="incidents" title="Incident causes" width="260" height="28" /> ``` ## Install [#install] ```tsx import { ParetoStrip } from "@microcharts/react/pareto-strip"; <ParetoStrip data={causes} unit="causes" metric="incidents" title="Incident causes" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a "fix these three" read in a KPI card, incident causes or support tags in a tab header, any long-tail composition where a few dominate. * **Avoid for** — a plain ranking (MiniBar) or parts of a single whole (SegmentedBar). ## Variants [#variants] ```tsx <ParetoStrip data={causes} threshold={false} />`" > <span className="inline-flex flex-col gap-2"> <ParetoStrip data="[ { label: "Timeouts", value: 38 }, { label: "OOM", value: 24 }, { label: "Deploy", value: 15 }, { label: "Config", value: 9 }, { label: "Network", value: 7 }, { label: "Auth", value: 4 }, ]" maxItems="3" title="Rolled up" width="240" height="26" /> <ParetoStrip data="[ { label: "Timeouts", value: 38 }, { label: "OOM", value: 24 }, { label: "Deploy", value: 15 }, { label: "Config", value: 9 }, { label: "Network", value: 7 }, { label: "Auth", value: 4 }, ]" threshold="false" title="No threshold" width="240" height="26" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <ParetoStrip data="[ { label: "Timeouts", value: 90 }, { label: "OOM", value: 6 }, { label: "Deploy", value: 4 }, ]" unit="causes" metric="incidents" title="One dominant cause" width="240" height="26" /> ``` ```tsx `" > <ParetoStrip data="[{ label: "a", value: 0 }]" metric="incidents" title="Nothing recorded" width="240" height="26" /> ``` ## Why this default [#why-this-default] The accent stops at the crossing, because the chart's one job is to say where to stop reading. The cumulative scale is fixed 0–100% and shares the full plot height — never rescaled to make the curve look steeper — and 80% is a **reference** default you can move or turn off, never a claimed law. `Other` is rendered honestly at its true size but always last and never counted among the vital few; if it towers over the top cause, that usually means `maxItems` is set too aggressively. ## Accessibility [#accessibility] The accessible name states the vital-few count and its cumulative — **"Top 1 of 3 causes account for 90% of incidents."** — or, when there is no threshold (or no ranked cause reaches it), the top cause and its share, as in the rolled-up demo above: **"Timeouts leads at 39%."** The interactive entry steps the bars and announces each bar's share and running cumulative; **T** jumps to the crossing bar. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value }[]` | Categories with magnitudes — the component sorts descending. | | `threshold` | `number \| false` | Cumulative reference line % (default 80 — a working reference, not a law). | | `maxItems` | `number` | Categories beyond maxItems roll up into Other (default 8, always last). | | `unit` | `string` | Category noun for the summary (default 'causes'). | | `metric` | `string` | Total-metric noun for the summary (default 'the total'). | | `label` | `"count" \| "none"` | 'K of N → cum%' in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # PartitionStrip (/docs/charts/partition-strip) PartitionStrip answers "what is the whole made of — and what are the big parts made of — with parentage visible?". Parents sit on the top row with widths proportional to their share of the whole, and each parent's children tile the exact x-range beneath it. Two aligned rows beat a treemap because alignment is the comparison channel — and two levels is a hard limit, because deeper hierarchies become unreadable texture at this size. ```tsx `" > <PartitionStrip data="[ { label: "JS", children: [{ label: "react", value: 28 }, { label: "vendor", value: 12 }, { label: "app", value: 8 }] }, { label: "CSS", children: [{ label: "tailwind", value: 16 }, { label: "custom", value: 8 }] }, { label: "img", value: 18 }, { label: "font", value: 10 }, ]" title="Bundle composition" width="320" height="30" /> ``` ## Install [#install] ```tsx import { PartitionStrip } from "@microcharts/react/partition-strip"; <PartitionStrip data={bundle} title="Bundle composition" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — bundle / storage / budget composition, two-level breakdowns. * **Avoid for** — deep hierarchies (unreadable at this size) or flat parts (SegmentedBar). ## Variants [#variants] ```tsx `" > <PartitionStrip data="[ { label: "JS", children: [ { label: "react", value: 28 }, { label: "vendor", value: 12 }, { label: "app", value: 8 }, ], }, { label: "CSS", children: [ { label: "tailwind", value: 16 }, { label: "custom", value: 8 }, ], }, { label: "img", value: 18 }, ]" emphasis="react" title="react emphasised" width="320" height="30" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <PartitionStrip data="[ { label: "img", value: 18 }, { label: "font", value: 10 }, { label: "css", value: 6 }, ]" title="Flat parts" width="220" height="24" /> ``` ```tsx `" > <PartitionStrip data="[ { label: "JS", children: [ { label: "react", value: 28 }, { label: "vendor", value: 12 }, ], }, { label: "CSS", children: [{ label: "tailwind", value: 16 }] }, ]" title="Squeezed" width="220" height="18" /> ``` ## Why this default [#why-this-default] Two aligned rows because alignment is the comparison — you can see at a glance that a child sits under its parent and how much of it that child is. A treemap discards that alignment and a flat SegmentedBar discards the hierarchy entirely. Grandchildren are ignored with a dev warning, on purpose: three levels of nesting at 24px is texture, not information. ## Accessibility [#accessibility] The accessible name names the biggest leaf and its parent — **"3 groups, 5 parts; largest JS → react (31% of the whole)."** The interactive entry roves within a row with ←/→ and moves between a parent and its children with ↑/↓, announcing each node's share of the whole and of its parent. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label, value?, children? }[]` | Two-level hierarchy. | | `emphasis` | `string` | Accents one node and its lineage. | | `labels` | `boolean` | Parent-row labels with size drop-out. | | `colors` | `string[]` | Per-group colours, cycled; overrides --mc-cat-N. Accent/neutral roles keep. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # PercentileLadder (/docs/charts/percentile-ladder) PercentileLadder answers "what does the tail look like — not just the median?". Ticks at the chosen percentiles sit on a zero-anchored track; graduated height and accent make the **tail** read strongest. Tick distances carry the story, so the origin is never cropped — and a log transform (for long latency tails) is never silent: an in-chart `log` tag renders when it applies. ```tsx i < 130 ? 90 + (i % 50) : i < 180 ? 150 + ((i * 7) % 320) : i < 196 ? 480 + ((i * 11) % 900) : 1500 + ((i * 13) % 800), )} title="Request latency" />`" > <PercentileLadder data="Array.from({ length: 200 }, (_, i) => (i < 130 ? 90 + (i % 50) : i < 180 ? 150 + ((i * 7) % 320) : i < 196 ? 480 + ((i * 11) % 900) : 1500 + ((i * 13) % 800)))" title="Request latency" width="240" height="18" /> ``` ## Install [#install] ```tsx import { PercentileLadder } from "@microcharts/react/percentile-ladder"; <PercentileLadder data={Array.from({ length: 200 }, (_, i) => i < 130 ? 90 + (i % 50) : i < 180 ? 150 + ((i * 7) % 320) : i < 196 ? 480 + ((i * 11) % 900) : 1500 + ((i * 13) % 800), )} format={{ style: "unit", unit: "millisecond" }} title="Request latency" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — latency SLOs in a sentence, the tail per endpoint in tables, payment-size spread. * **Avoid for** — the odds of an outcome (QuantileDots) or the full distribution shape (MicroBox). ## Variants [#variants] ```tsx i < 130 ? 90 + (i % 50) : i < 180 ? 150 + ((i * 7) % 320) : i < 196 ? 480 + ((i * 11) % 900) : 1500 + ((i * 13) % 800), ); <PercentileLadder data={latencies} scale="log" /> <PercentileLadder data={latencies} ps={[50, 95, 99.9]} label="values" /> <PercentileLadder data={latencies} marks="dot" /> // value labels and the summary format through Intl — "1.661 ms", not "1,661 ms" <PercentileLadder data={latencies} label="values" format={{ style: "unit", unit: "millisecond", maximumFractionDigits: 0 }} locale="de-DE" />`" > <span className="inline-flex flex-col gap-2"> <PercentileLadder data="Array.from({ length: 200 }, (_, i) => i < 130 ? 90 + (i % 50) : i < 180 ? 150 + ((i * 7) % 320) : i < 196 ? 480 + ((i * 11) % 900) : 1500 + ((i * 13) % 800), )" scale="log" title="Log scale" width="220" height="18" /> <PercentileLadder data="Array.from({ length: 200 }, (_, i) => i < 130 ? 90 + (i % 50) : i < 180 ? 150 + ((i * 7) % 320) : i < 196 ? 480 + ((i * 11) % 900) : 1500 + ((i * 13) % 800), )" ps="[50, 95, 99.9]" label="values" title="Strict SLOs" width="220" height="20" /> <PercentileLadder data="Array.from({ length: 200 }, (_, i) => i < 130 ? 90 + (i % 50) : i < 180 ? 150 + ((i * 7) % 320) : i < 196 ? 480 + ((i * 11) % 900) : 1500 + ((i * 13) % 800), )" marks="dot" title="Dot marks" width="220" height="18" /> <PercentileLadder data="Array.from({ length: 200 }, (_, i) => i < 130 ? 90 + (i % 50) : i < 180 ? 150 + ((i * 7) % 320) : i < 196 ? 480 + ((i * 11) % 900) : 1500 + ((i * 13) % 800), )" label="values" format="{ style: "unit", unit: "millisecond", maximumFractionDigits: 0 }" locale="de-DE" title="de-DE locale" width="260" height="18" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <PercentileLadder data="[7, 7, 7, 7]" title="All equal" width="120" height="14" /> ``` ```tsx `" > <PercentileLadder data="[0, 10, 100, 1000]" scale="log" title="Falls back" width="120" height="14" /> ``` ```tsx `" > <PercentileLadder data="[10, 20, 30, 90, 900]" title="Too narrow for labels" width="40" height="14" /> ``` ## Why this default [#why-this-default] The default linear track is zero-anchored — tick **distances** carry the story, so cropping the origin would distort every gap between percentiles. Height and accent grow toward the tail because the tail, not the median, is usually the SLO question. A log transform for long tails is never silent: it only applies when every sample is strictly positive, and an in-chart `log` tag renders whenever it does, so the axis is never misread as linear. ## Accessibility [#accessibility] The accessible name states every marked percentile and the tail's multiple of the median — **"p50 124.5, p90 488.1, p99 1,661.13 — the slowest 1% take 13.3× the median."** The interactive entry roves ticks with ←/→ (Home/End jump to the ends), announcing each tick's value and its multiple of the median (**"p99: 1,661.13 — 13.3× the median."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Raw sample; quantiles are derived. | | `ps` | `number[]` | Percentiles to mark (default [50, 90, 99], 2–4). | | `scale` | `"linear" \| "log"` | Log for long tails (falls back on any value ≤ 0; renders a log tag). | | `label` | `"ps" \| "values" \| "both" \| "none"` | What the tick labels state. | | `marks` | `"tick" \| "dot"` | Tick marks (default) or dot marks — dots read calmer over dense text. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # PercentileTrace (/docs/charts/percentile-trace) PercentileTrace answers "is this entity's standing rising or slipping inside the pack?". It traces one **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, not estimates — so the only line on the chart is the entity itself, drifting through a known landscape. ```tsx `" > <PercentileTrace data="[40, 46, 52, 58, 63, 68, 72, 76, 79, 81]" unit="week" label="last" title="Standing" width="260" height="30" /> ``` ## Install [#install] ```tsx import { PercentileTrace } from "@microcharts/react/percentile-trace"; <PercentileTrace data={ranks} title="Standing" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — one player's or product's rank drifting over time, whether a standing has crossed into the top or bottom of the pack, a percentile KPI where the population context matters. * **Avoid for** — a raw value over time (Sparkline) or one absolute number vs a target (Bullet / Delta). ## Variants [#variants] ```tsx <PercentileTrace data={[40, 46, 52, 58, 63, 68, 72, 76, 79, 81]} showBands={false} />`" > <span className="inline-flex flex-col gap-1.5"> <PercentileTrace data="[40, 46, 52, 58, 63, 68, 72, 76, 79, 81]" unit="week" title="with bands" width="220" height="28" /> <PercentileTrace data="[40, 46, 52, 58, 63, 68, 72, 76, 79, 81]" showBands="false" unit="week" title="no bands" width="220" height="28" /> </span> ``` 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 (a support ticket's backlog rank, say). The line already encodes the direction, so the color is only a redundant cue — never the sole signal. ```tsx `" > <PercentileTrace data="[78, 72, 64, 55, 47, 40, 34, 29, 26, 24]" positive="down" unit="week" title="down is good" width="220" height="28" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <PercentileTrace data="[63]" unit="week" title="Single reading" width="140" height="26" /> ``` ```tsx `" > <PercentileTrace data="[102, 88, 96]" unit="week" title="Clamped ranks" width="180" height="26" /> ``` ```tsx `" > <PercentileTrace data="[40, 55, 68, 81.5]" format="{ maximumFractionDigits: 1 }" locale="de-DE" label="last" unit="week" title="Localized percentile" width="180" height="26" /> ``` 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. ## Why this default [#why-this-default] The full 0–100 axis with fixed bands, because a percentile is a standing *within a population* — truncating the axis would hide how much headroom or floor is left, and re-estimating the bands from the single traced series would be a fiction. The middle-half and near-full fields are exact by construction, so the chart shows one honest line over a landscape you can trust, never a thicket of competing series. ## Accessibility [#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](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `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` | (interactive) Reading noun for the interactive announcement (default 'step'). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # PhaseTrace (/docs/charts/phase-trace) PhaseTrace answers "how do two coupled signals move *together*?". Plotting one against the other as a single trajectory turns lag into loops and regimes into clusters — structure that two separate sparklines hide. Path order carries time, and the current state is a directed endpoint with an arrowhead, so "now, and how it got here" reads at a glance. ```tsx { const t = (i / 40) * Math.PI * 2; return { x: 55 + Math.cos(t) * 22, y: 110 + Math.sin(t - 0.9) * 40 }; })} xLabel="CPU" yLabel="Latency" title="Phase portrait" />`" > <PhaseTrace data="Array.from({ length: 40 }, (_, i) => { const t = (i / 40) * Math.PI * 2; return { x: 55 + Math.cos(t) * 22, y: 110 + Math.sin(t - 0.9) * 40 }; })" xLabel="CPU" yLabel="Latency" title="Phase portrait" width="110" height="100" /> ``` ## Install [#install] ```tsx import { PhaseTrace } from "@microcharts/react/phase-trace"; <PhaseTrace data={trajectory} xLabel="CPU" yLabel="Latency" title="Phase portrait" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — coupled-signal phase portraits (CPU × latency, inflation × unemployment). * **Avoid for** — reading exact values (DualSparkline) or a single series (Sparkline). ## Variants [#variants] ```tsx { const t = (i / 40) * Math.PI * 2; return { x: 55 + Math.cos(t) * 22, y: 110 + Math.sin(t - 0.9) * 40 }; })} tail={0.4} startDot />`" > <PhaseTrace data="Array.from({ length: 40 }, (_, i) => { const t = (i / 40) * Math.PI * 2; return { x: 55 + Math.cos(t) * 22, y: 110 + Math.sin(t - 0.9) * 40 }; })" xLabel="CPU" yLabel="Latency" tail="0.4" title="Longer tail" width="110" height="100" /> ``` ```tsx `" > <PhaseTrace data="[ { x: 1200, y: 4500 }, { x: 1450, y: 4100 }, { x: 1800, y: 3600 }, ]" xLabel="Requests" yLabel="Errors" locale="de-DE" title="Localized coordinates" width="90" height="80" /> ``` With a `locale`, the accessible summary's coordinates follow that locale's own grouping — "1.800" in German, not "1,800". In-chart marks carry no text, so only the announced numbers change. ## Edge cases [#edge-cases] ```tsx `" > <PhaseTrace data="[{ x: 55, y: 62 }]" xLabel="CPU" yLabel="Latency" title="One observation" width="80" height="72" /> ``` ```tsx ({ x: 40, y: 40 }))} xLabel="CPU" yLabel="Latency" />`" > <PhaseTrace data="Array.from({ length: 8 }, () => ({ x: 40, y: 40 }))" xLabel="CPU" yLabel="Latency" title="No motion" width="80" height="72" /> ``` A single observation draws only the accent endpoint dot — there's no history to trail and no motion for an arrowhead to point along. When every point in the tail window is coincident (or nearly so, within 0.5% of the combined axis span), the heading resolves to the fifth, explicit "steady" state rather than a jittery direction from noise. ## Why this default [#why-this-default] A muted trail with an accent tail because "now, and how it got here" is the question — the eye lands on the recent motion first, then reads the history. Axis and scale choices are stated, never silently transformed: the axes are named in the summary, and the domains are always linear. The tail, endpoint, and arrowhead trio may be restyled but never all removed, because the recoverable time direction is what separates a phase trace from a scatter. ## Accessibility [#accessibility] The accessible name states the current point and heading, with the y-axis named first — for the hero example above, **"Latency vs CPU: now 76.729, 75.163; heading down-right."** The interactive entry steps through the trajectory in time order with ←/→, announcing each point's index and its value on both named axes. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ x, y }[]` | Two synchronized signals, time-ordered. | | `xLabel / yLabel` | `string` | Axis names — the summary reads them. | | `xDomain` | `[number, number]` | Fix the x-axis range (default: the data's x-extent). | | `domain` | `[number, number]` | Fix the y-axis range (default: the data's y-extent). | | `tail` | `number` | Fraction of points drawn in accent (recent motion). | | `grid` | `boolean` | Quadrant hairlines for regime reads. | | `startDot` | `boolean` | Anchor the path's origin for full-journey reads (default false). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # PictogramRow (/docs/charts/pictogram-row) PictogramRow answers "how many of the N units are filled?" — ●●●○○ — counts a human can verify by counting. Filled vs hollow is a shape difference too, never opacity alone, and unit size is constant: scaling glyphs with value is the classic pictogram lie this component refuses to tell. ```tsx <span className="text-lg"> {"The coalition holds "} <PictogramRow value="5" total="8" title="Committee seats held" style="{ width: "4.5em", height: "0.9em" }" /> {" of the seats."} </span> ``` ## Install [#install] ```tsx import { PictogramRow } from "@microcharts/react/pictogram-row"; <PictogramRow value={5} total={8} title="Committee seats held" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — seats, slots, and ratings in a sentence; capacity rows in tables. * **Avoid for** — more than 20 units (counting fails; use Progress) or continuous ratios (Progress). ## Variants [#variants] ```tsx `" > <PictogramRow value="2.5" total="4" title="True partial" width="90" height="18" /> ``` ```tsx `" > <PictogramRow value="2.5" total="4" fractional="round" title="Whole seats" width="90" height="18" /> ``` ```tsx `"> <PictogramRow value="3" total="5" shape="square" title="Squares" width="90" height="18" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <PictogramRow value="3" total="0" title="No capacity" width="90" height="18" /> ``` ```tsx `"> <PictogramRow value="-2" total="4" title="Deficit" width="90" height="18" /> ``` ```tsx `"> <PictogramRow value="9" total="8" title="Over capacity" width="90" height="18" /> ``` A `total` of 0 (or non-finite) draws nothing and the summary is "No data." — there is no meaningful row to count. A negative value renders every unit hollow, and the summary still states the true number ("-2 of 4.") rather than clamping to 0. A value past the total fills every unit — never more than `total` units drawn — but the summary keeps the honest count ("9 of 8.") with a dev-time warning, so the overflow is never hidden. ## Why this default [#why-this-default] Clip over round — the partial unit is real data, drawn as a true circular segment (not a `clipPath`, which would need generated ids that break server rendering determinism). Overflow renders all units filled but the summary keeps the true numbers ("9 of 8.") with a dev warning; the chart never silently caps the figure. ## Accessibility [#accessibility] The accessible name is the count — **"3 of 5."** — with the context noun coming from your `title` ("Committee seats held. 3 of 5."). The interactive entry re-announces when the value changes, and roving the units announces each one on its own: on the 5-of-8 demo at the top of this page, the fourth unit says "Unit 4 of 8 — filled." A unit reads as empty, filled, or, for a genuinely partial one, the percentage it holds. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | Filled units (may be fractional). | | `total` (required) | `number` | Unit count. | | `shape` | `"dot" \| "square"` | Squares pack tighter in table cells. | | `fractional` | `"clip" \| "round"` | Clip shows the true partial unit; round for seat-like units. | | `renderPoint` | `(unit) => ReactNode` | Custom unit glyph (star ratings) — the one sanctioned customization. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # PolarClock (/docs/charts/polar-clock) PolarClock answers "what's the shape of the day or week cycle — when is it busy?" Each value in the cycle becomes a radial bar at its fixed angle, growing outward from an inner baseline; longer bars are busier times. Midnight (or your week-start) sits at 12 o'clock and the cycle runs clockwise, so the rhythm of a metric across the cycle is immediately legible. ```tsx <PolarClock data="Array.from({ length: 24 }, (_, h) => (h === 14 ? 312 : h === 4 ? 20 : 80 + h))" now="14" title="Traffic by hour" size="72" /> ``` ## Install [#install] ```tsx import { PolarClock } from "@microcharts/react/polar-clock"; <PolarClock data={byHour} now={14} title="Traffic by hour" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — the shape of a 24-hour or 7-day cycle, when a metric is busy across the cycle, or a compact seasonal read in a KPI card. * **Avoid for** — exact value comparison (unroll the cycle into a `SparkBar`), a non-cyclic trend (`Sparkline`), or more than a few dozen segments. ## Variants [#variants] ```tsx (h === 14 ? 312 : h === 4 ? 20 : 80 + h)); const week = [120, 200, 180, 210, 260, 90, 60]; <PolarClock data={byHour} label="max" /> <PolarClock data={week} mode="opacity" />`" > <span className="inline-flex gap-6 items-center"> <PolarClock data="Array.from({ length: 24 }, (_, h) => (h === 14 ? 312 : h === 4 ? 20 : 80 + h))" label="max" size="64" summary="false" /> <PolarClock data="[120, 200, 180, 210, 260, 90, 60]" mode="opacity" size="56" summary="false" /> </span> ``` ```tsx (h === 14 ? 312 : h === 4 ? 20 : 80 + h)); <PolarClock data={byHour} labels={false} />`" > <PolarClock data="Array.from({ length: 24 }, (_, h) => (h === 14 ? 312 : h === 4 ? 20 : 80 + h))" labels="false" size="64" summary="false" /> ``` ```tsx (h === 14 ? 1240 : h === 4 ? 20 : 80 + h)); <PolarClock data={byHour} label="max" locale="de-DE" />`" > <PolarClock data="Array.from({ length: 24 }, (_, h) => (h === 14 ? 1240 : h === 4 ? 20 : 80 + h))" label="max" locale="de-DE" title="Localized peak" size="64" /> ``` ## Why this default [#why-this-default] The channel is radial **length from the inner baseline**, not sector area. Equal-value bars at the rim span more area than ones near the hub, so an area reading would exaggerate the outer segments — the inner radius is nonzero precisely to curb that distortion, and the docs ask you to compare lengths, not wedges. Bars are always zero-anchored at that baseline. For very small sizes where length is hard to judge, `mode="opacity"` switches the channel to a five-step fill — a radial `ActivityGrid` — which is a deliberate, named change of encoding, not a cosmetic one. A `null` segment leaves a gap (the baseline ring shows the hole) because missing is not the same as zero. The four cardinal ticks default **on** because a bare ring of bars is rotationally ambiguous — without a mark for "12 o'clock" there is no way to tell where the cycle starts, so "when is it busy" can't be answered from the static frame alone. The four ticks are merged into one path (a single node), so the orientation cue is free of the usual label-drop-out tradeoff — set `labels={false}` only when the shape itself is the whole story and the axis genuinely doesn't matter. ## Edge cases [#edge-cases] ```tsx `"> <PolarClock data="Array(24).fill(null)" title="No data yet" size="56" /> ``` ```tsx `"> <PolarClock data="Array(24).fill(50)" title="Steady" size="56" /> ``` ## Accessibility [#accessibility] The accessible name states the peak and the quiet point of the cycle — **"Peaks at 14:00 (1.240); quietest 04:00."** — with hour labels for a 24-segment cycle and weekday names for a 7-segment one. The interactive entry lets you arrow through the segments circularly, each announced with its label and value through a polite live region, and the accented `now` segment carries position and color, never color alone. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | One value per cycle division (24 hourly, 7 daily, any n). | | `now` | `number` | Index of the current segment to accent. | | `inner` | `number` | Inner radius fraction r0 — the zero baseline bars grow from (default 0.35). | | `mode` | `"length" \| "opacity"` | Radial bars (default) or fixed-length 5-step fill. | | `origin` | `number` | Index rendered at 12 o'clock (week-start / midnight). | | `labels` | `boolean` | Hairline cardinal ticks at 0/¼/½/¾ — the at-rest orientation cue. Default true. | | `segmentFormat` | `(index, n) => string` | Segment index → label (default: HH:00 for n=24, weekday for n=7, else index). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # ProgressRing (/docs/charts/progress-ring) ProgressRing answers "how complete is this?" at icon size, where a linear bar doesn't fit. The start angle is fixed at 12 o'clock and the caps are butt-cut — the two quiet ways rings inflate progress, both removed. It is never a gauge: no needle, no red zone. ```tsx `" > <ProgressRing value="0.68" label="percent" size="48" title="Backup" style="{ width: 72, height: 72 }" /> ``` ## Install [#install] ```tsx import { ProgressRing } from "@microcharts/react/progress-ring"; <ProgressRing value={0.68} title="Backup" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — tab headers, KPI card corners, cooldowns and retry timers (`sweep`). * **Avoid for** — precise reads (Progress — the % label is the datum there). ## Variants [#variants] ```tsx `" > <ProgressRing value="0.68" size="40" title="Cooldown" style="{ width: 56, height: 56 }" /> ``` ```tsx `"> <ProgressRing value="0.68" weight="6" size="40" title="Thick ring" style="{ width: 56, height: 56 }" /> ``` ```tsx `"> <ProgressRing value="0.68" label="percent" locale="de-DE" title="Localized percent" size="40" style="{ width: 56, height: 56 }" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <ProgressRing value="1.4" label="percent" title="Over budget" size="40" style="{ width: 56, height: 56 }" /> ``` ```tsx `"> <ProgressRing value="Number.NaN" label="percent" title="Unknown" size="40" style="{ width: 56, height: 56 }" /> ``` ## Why this default [#why-this-default] Butt caps and a fixed start: rounded caps overstate small fractions, and variable start angles make identical fractions look different. Past 100% the ring clamps while the center label carries the true percent — same contract as Progress. A full circle is drawn as two half-arcs (SVG cannot draw a single 360° arc). ## Accessibility [#accessibility] The accessible name reuses the progress wording — **"68% complete."**, or **"32% remaining."** in sweep mode. The interactive entry announces only at 25/50/75/100% threshold crossings — a streaming value never spams the screen reader. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The progressed amount. | | `max` | `number` | Denominator (default 1). | | `sweep` | `boolean` | Countdown: the REMAINING wedge shrinks. | | `weight` | `number` | Ring thickness (viewBox units). | | `label` | `"none" \| "percent"` | Centered figure (≥ 20 px rendered). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Progress (/docs/charts/progress) Progress answers "how far along is this, exactly?". The bar gives the instant read; the percent label *is* the datum — a bare bar is decoration. The track never shrinks for the label (the viewBox widens instead), so fractions stay comparable down a table column. ```tsx <Progress value="0.68" title="Onboarding" width="160" height="22" /> ``` ## Install [#install] ```tsx import { Progress } from "@microcharts/react/progress"; <Progress value={0.68} title="Onboarding" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — KPI cards, table completion columns, step counts (`segments`). * **Avoid for** — icon-size slots (ProgressRing) or composition (SegmentedBar). ## Variants [#variants] ```tsx `" > <Progress value="3" max="5" segments="5" label="fraction" title="Steps" width="160" height="22" /> ``` ```tsx <Progress value={0.68} label="none" />`" > <span className="inline-flex items-center gap-4"> <Progress value="34" max="50" label="value" title="Value label" width="140" height="22" /> <Progress value="0.68" label="none" title="Bare bar" width="110" height="22" /> </span> ``` ```tsx `" > <Progress value="0.68" positive="down" title="Budget burn" width="160" height="22" /> ``` ```tsx `"> <Progress value="34" max="50" label="value" locale="de-DE" title="Localized" width="140" height="22" /> ``` With `label="percent"` (the default) the accessible name follows `format`/`locale` too — "68 %" under `de-DE` rather than the English "68%". ## Edge cases [#edge-cases] ```tsx `" > <Progress value="112" max="100" title="Overshoot" width="160" height="22" /> ``` ```tsx `"> <Progress value="0" title="Not started" width="160" height="22" /> ``` ```tsx 0 — an empty track, // not an invented fraction <Progress value={5} max={0} title="Unknown goal" />`" > <Progress value="5" max="0" title="Unknown goal" width="160" height="22" /> ``` `max <= 0` (or a non-finite `value`/`max`) renders an empty track with no fill, and the label becomes an em dash ("—") rather than a fabricated number — the accessible name says "No data." instead of computing a meaningless ratio. A `value` of `0` renders a real, empty-but-present bar (not the no-data state), so "not started" and "unmeasurable" stay visually distinct. ## Why this default [#why-this-default] The percent label is on by default because it is the datum — the bar alone can't say "68%". Past 100% the bar clamps at full but the label carries the true figure ("112%"): the number and the bar only ever disagree in that one documented case, and the number wins. `max <= 0` renders an empty track and says "No data." rather than inventing a fraction. `max` — not `total` — is the deliberate exception across the library: every other denominator prop names a discrete count (`total` on IconArray, TallyMarks, Honeycomb…), but Progress tracks a continuous goal that can be overshot, so it keeps the word that says "ceiling," not "count." ## Accessibility [#accessibility] The accessible name is the completion — **"68% complete."**, or **"3 of 5 steps."** when segmented, or **"32% remaining."** with `positive="down"`. The interactive entry re-announces through a polite live region, throttled to whole-percent changes so a streaming value doesn't spam screen readers, and the fill-width transition is gated on reduced motion. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The progressed amount. | | `max` | `number` | Denominator (default 1). | | `segments` | `number` | Discrete-chunk track — the chart says step count, not ratio. | | `label` | `"percent" \| "value" \| "fraction" \| "none"` | The direct label; percent is the default datum. | | `positive` | `"up" \| "down"` | down = burn-down wording (summary only; the bar stays factual). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # QuadrantDot (/docs/charts/quadrant-dot) QuadrantDot answers "where does this item sit in the 2×2 — against the field?". A focal dot is placed by 2-D position, a hairline cross marks the split (the domain midpoints by default, always overridable but **never hidden**), and the peers show as tiny muted ghosts. The read is quadrant **membership** first; exact position is the second read — which is why it lives at glyph scale. ```tsx <QuadrantDot data="{ x: 3, y: 9 }" field="[ { x: 2, y: 8 }, { x: 8, y: 9 }, { x: 3, y: 7 }, { x: 9, y: 2 }, { x: 7, y: 3 }, { x: 1, y: 1 }, { x: 5, y: 6 }, { x: 6, y: 8 }, { x: 4, y: 3 }, { x: 8, y: 5 }, { x: 2, y: 4 }, { x: 7, y: 7 }, { x: 3, y: 2 }, { x: 6, y: 1 }, ]" xDomain="[0, 10]" domain="[0, 10]" xLabel="effort" yLabel="impact" title="Effort vs impact" width="96" height="96" /> ``` ## Install [#install] ```tsx import { QuadrantDot } from "@microcharts/react/quadrant-dot"; <QuadrantDot data={item} field={backlog} xLabel="effort" yLabel="impact" title="Effort vs impact" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — the classic prioritization 2×2 (one cell per initiative in a table), an effort-vs-impact read in a KPI card, any "which quadrant, against the field" decision. * **Avoid for** — a full scatter plot (MicroScatter) or a single ranked list (MiniBar). ## Variants [#variants] ```tsx <QuadrantDot data={item} field={backlog} quadrants={["quick win", "big bet", "skip", "time sink"]} />`" > <span className="inline-flex gap-4 items-center"> <QuadrantDot data="{ x: 3, y: 9 }" xDomain="[0, 10]" domain="[0, 10]" split="[5, 5]" xLabel="effort" yLabel="impact" width="72" height="72" /> <QuadrantDot data="{ x: 3, y: 9 }" field="[ { x: 2, y: 8 }, { x: 8, y: 9 }, { x: 9, y: 2 }, { x: 6, y: 1 }, { x: 4, y: 3 }, ]" xDomain="[0, 10]" domain="[0, 10]" quadrants="["quick win", "big bet", "skip", "time sink"]" width="72" height="72" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <QuadrantDot data="{ x: 5, y: 5 }" field="[ { x: 1, y: 5 }, { x: 8, y: 5 }, ]" xLabel="effort" yLabel="impact" title="Flat impact" width="72" height="72" /> ``` ```tsx `"> <QuadrantDot data="{ x: 5, y: 5 }" field="[ { x: 5, y: 5 }, { x: 1, y: 1 }, ]" xLabel="effort" yLabel="impact" title="Coincident peer" width="72" height="72" /> ``` ```tsx `"> <QuadrantDot data="{ x: Number.NaN, y: 5 }" title="Bad input" width="72" height="72" /> ``` When every field value on one axis equals the focal's, that axis's domain collapses to a point — the split line on that axis is dropped rather than drawn at an arbitrary spot, while the other axis's split still renders. A peer exactly on top of the focal is still counted (distance 0) and sorts first in the interactive entry's nearest-first order. A non-finite focal position draws no marks at all — no cross, no tint, no peers — and carries the "No data." summary, the same degenerate path an empty series takes elsewhere in the library. ## Why this default [#why-this-default] 24×24, because the 2×2 is a **position** read, not a scatter plot — you want to know the quadrant at a glance, and the exact coordinates only when you look closer. The split is data, not decoration: it renders wherever the split truly is and is always overridable, never invisible. With the axes unlabeled at glyph size, the `title` and `summary` are load-bearing — skipping them is the one named anti-pattern for this chart, so always pass `xLabel`, `yLabel`, and a `title`. ## Accessibility [#accessibility] The accessible name states the focal position and the axis-relative quadrant — **"Impact 9, effort 3 — in the high-impact, low-effort quadrant."** — adding how crowded that quadrant is when a `field` is given, or your own words via `quadrants={["quick win", …]}`. The interactive entry starts on the focal, then cycles peers nearest-first — each announced with its coordinates and quadrant. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ x; y }` | The focal item's 2-D position. | | `field` | `{ x; y }[]` | The peer set — omit for a lone glyph. | | `xDomain` | `[number, number]` | The x-axis range (default: derived from the data); domain stays the y-axis. | | `domain` | `[number, number]` | The y-axis range (default: derived from the data). | | `split` | `[number, number]` | The quadrant boundary (default domain midpoints) — never hidden. | | `quadrants` | `[TL, TR, BL, BR]` | Names in reading order — summaries only, never rendered. | | `xLabel / yLabel` | `string` | Axis nouns for the summary — pass them, the axes are unlabeled at glyph size. | | `region` | `boolean` | Faint tint on the focal's quadrant (default true; false for dense grids). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # QuantileDots (/docs/charts/quantile-dots) QuantileDots answers "what are the odds?" — in **countable** form. It's a quantile dotplot: each dot is an equal-probability quantile, so a dot is roughly a **1-in-N chance**, not a raw observation. Add a `threshold` and the plot turns from shape into odds: the dots past the line are re-inked and ringed, and the summary reads **"N in 20"** — because odds you can count beat odds you must trust, and a frequency reads truer than a bare percentage. ```tsx <QuantileDots data="Array.from({ length: 200 }, (_, i) => Math.round(4 + (i % 30) * 0.35 + ((i * 7) % 13) * 1.1 + (i % 50 === 0 ? 20 : 0)), )" threshold="15" format="{ style: "unit", unit: "minute", unitDisplay: "short", maximumFractionDigits: 0 }" title="Bus wait" width="260" height="30" /> ``` ## Install [#install] ```tsx import { QuantileDots } from "@microcharts/react/quantile-dots"; <QuantileDots data={waits} threshold={15} format={(n) => `${n} min`} title="Bus wait" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a "will we miss the SLA?" read in a sentence, odds you can count in a KPI card, a posterior communicated as frequency rather than percent. * **Avoid for** — a precise distribution shape (HistogramStrip) or one estimate's interval (GradedBand). ## Variants [#variants] ```tsx <QuantileDots data={waits} threshold={10} side="below" />`" > <span className="inline-flex flex-col gap-1.5"> <QuantileDots data="Array.from({ length: 200 }, (_, i) => Math.round(4 + (i % 30) * 0.35 + ((i * 7) % 13) * 1.1 + (i % 50 === 0 ? 20 : 0)), )" count="15" threshold="15" format="{ style: "unit", unit: "minute", unitDisplay: "short", maximumFractionDigits: 0 }" title="15 dots" width="220" height="28" /> <QuantileDots data="Array.from({ length: 200 }, (_, i) => Math.round(4 + (i % 30) * 0.35 + ((i * 7) % 13) * 1.1 + (i % 50 === 0 ? 20 : 0)), )" threshold="10" side="below" format="{ style: "unit", unit: "minute", unitDisplay: "short", maximumFractionDigits: 0 }" title="under 10 min" width="220" height="28" /> </span> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, the announced threshold follows that locale's own grouping and decimal marks. ```tsx `" > <QuantileDots data="Array.from({ length: 200 }, (_, i) => Math.round(4000 + (i % 30) * 350 + ((i * 7) % 13) * 1100 + (i % 50 === 0 ? 20000 : 0)), )" threshold="15000" format="{ style: "unit", unit: "minute", unitDisplay: "narrow" }" locale="de-DE" title="Localized threshold" width="220" height="26" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <QuantileDots data="[]" title="No samples" width="140" height="20" /> ``` ```tsx `"> <QuantileDots data="[7, 7, 7, 7, 7]" title="Certain outcome" width="140" height="20" /> ``` ```tsx `"> <QuantileDots data="Array.from({ length: 200 }, (_, i) => Math.round(4 + (i % 30) * 0.35 + ((i * 7) % 13) * 1.1))" threshold="9999" side="above" title="Threshold past the max" width="140" height="20" /> ``` Empty data draws nothing and the summary says so plainly. An all-equal sample collapses every dot into one column — genuine certainty, not a rendering glitch. A threshold outside the observed range reads as 0 in N (or N in N) — the count is always honest about what fraction of the field it's actually catching. ## Why this default [#why-this-default] 20 dots, because odds you can count beat odds you must trust — a reader subitizes a handful of highlighted dots faster than they parse "48%". Each dot is an equal-probability quantile, **not** a raw observation, and the summary always frames the answer as a frequency ("10 in 20"), never a bare percentage. Dots past the threshold are re-inked **and** ringed, so the count survives grayscale, print, and forced-colors. ## Accessibility [#accessibility] The accessible name states the odds in frequency form — **"8 in 15 chances above 15 min."** — or, without a threshold, "Most likely …; range …". The interactive entry is a probe: hovering or arrowing moves a live threshold and the count past it recomputes as you go. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Raw sample or posterior draws — the component derives the quantile dots. | | `count` | `number` | Number of quantile dots (default 20; 15–20 recommended; capped at 25). | | `threshold` | `number` | The decision line — turns the plot from shape into odds. | | `side` | `"above" \| "below"` | Which side of the threshold is the event being counted. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # QueueDepth (/docs/charts/queue-depth) QueueDepth answers "is the backlog draining or growing?". It draws the queue **depth** as a zero-anchored area — a stock, not a rate — against a dashed **capacity** hairline. Wherever the depth runs above capacity, the top edge is re-stroked in the negative ink, so a breach is a change in *shape* as well as color. The endpoint carries the current value and a trend glyph (▴/▾) fit over the last quarter of the window. ```tsx <QueueDepth data="[42, 55, 70, 88, 96, 120, 150, 182, 214]" capacity="100" title="Support queue" width="260" height="30" /> ``` ## Install [#install] ```tsx import { QueueDepth } from "@microcharts/react/queue-depth"; <QueueDepth data={[42, 55, 70, 88, 96, 120, 150, 182, 214]} capacity={100} title="Support queue" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a support-queue backlog in a KPI card, a work-in-progress stock against its WIP limit, will-it-drain in a tab header. * **Avoid for** — a rate rather than a stock (Sparkline) or a single count (Delta). ## Variants [#variants] ```tsx <QueueDepth data={backlog} /> <QueueDepth data={backlog} capacity={100} label="none" />`" > <span className="inline-flex flex-col gap-1.5"> <QueueDepth data="[214, 190, 150, 120, 96, 70, 48]" capacity="100" title="Draining" width="220" height="28" /> <QueueDepth data="[42, 55, 70, 88, 96, 120, 150, 182, 214]" title="No capacity reference" width="220" height="28" /> <QueueDepth data="[42, 55, 70, 88, 96, 120, 150, 182, 214]" capacity="100" label="none" title="No label" width="220" height="28" /> </span> ``` ```tsx `" > <QueueDepth data="[420, 560, 720, 880, 1040, 1280, 1560, 1880, 2140]" capacity="1000" locale="de-DE" title="Localized backlog" width="220" height="28" /> ``` With a `locale`, both the endpoint label and the accessible summary's numbers follow that locale's own grouping — the summary reads **"2.140 queued, 2,1× capacity, growing over the last quarter."** in German, not "2,140 queued, 2.1× capacity". ## Edge cases [#edge-cases] ```tsx `" > <QueueDepth data="[42, 55, 70, 88, 96, 120, 150, 182, 214]" title="No capacity" width="220" height="28" /> ``` ```tsx `"> <QueueDepth data="[90, 70, 50, 30]" capacity="100" title="Draining" width="220" height="28" /> ``` ```tsx `" > <QueueDepth data="[10, null, 40, null, 80, 120]" capacity="100" title="Gaps" width="220" height="28" /> ``` With no `capacity`, the area still draws and the summary reads **"214 queued, growing over the last quarter."** — no capacity clause, because there's nothing to compare against. A queue that stays under capacity reports **"30 queued, within capacity, draining over the last quarter."** and never re-strokes the edge. Gaps (`null`/`NaN`/`±Infinity`) split the area into separate runs rather than drawing a line across missing periods. ## Why this default [#why-this-default] The capacity hairline plus the negative re-stroke, because "are we keeping up?" is a threshold question — a breach should read instantly and survive greyscale, so it changes the edge's *shape*, not only its color. The trend glyph is deliberately low-precision: it's fit over the last quarter of the window as a direction cue, and the summary states that window in words ("over the last quarter") rather than implying a forecast the data can't support. ## Accessibility [#accessibility] The accessible name states the current depth, the capacity relationship, and the trend — **"214 queued, 2.1× capacity, growing over the last quarter."**. When the depth stays under capacity the middle clause becomes "within capacity"; with no `capacity` it drops entirely. The interactive entry steps the periods, announcing each depth and whether it's above capacity (**"t8: 214 queued, above capacity."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Backlog depth per period (≥ 0). null / NaN / ±Infinity are gaps. | | `capacity` | `number` | Steady-state capacity: a dashed hairline; spans above it re-stroke negative. | | `label` | `"last" \| "none"` | Endpoint value + trend glyph (▴/▾), default 'last', or nothing. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # RateVolume (/docs/charts/rate-volume) RateVolume answers "the rate moved — on what volume?". A precise rate line rides over deliberately low-precision **ghost volume bars** — the denominator. There is no prop to remove the bars: a rate without its denominator is the lie this type exists to prevent. A 4.1% conversion rate reads very differently on 38 events than on 3,800. ```tsx <RateVolume data="[ { rate: 0.023, volume: 220 }, { rate: 0.025, volume: 190 }, { rate: 0.028, volume: 160 }, { rate: 0.029, volume: 130 }, { rate: 0.031, volume: 110 }, { rate: 0.034, volume: 90 }, { rate: 0.036, volume: 66 }, { rate: 0.041, volume: 38 }, ]" format="{ style: "percent", maximumFractionDigits: 1 }" minVolume="50" label="last" title="Conversion rate" width="260" height="28" /> ``` ## Install [#install] ```tsx import { RateVolume } from "@microcharts/react/rate-volume"; <RateVolume data={periods} minVolume={50} title="Conversion rate" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a conversion / error rate with its denominator, a KPI card where the rate is the headline, spotting a big rate move on thin volume. * **Avoid for** — volume itself needing a precise read (pair a SparkBar) or a plain series (Sparkline). ## Variants [#variants] ```tsx <RateVolume data={periods} curve="step" />`" > <span className="inline-flex flex-col gap-1.5"> <RateVolume data="[ { rate: 0.023, volume: 220 }, { rate: 0.028, volume: 160 }, { rate: 0.031, volume: 110 }, { rate: 0.036, volume: 66 }, { rate: 0.041, volume: 38 }, ]" format="{ style: "percent", maximumFractionDigits: 1 }" minVolume="50" title="Low-volume flag" width="220" height="26" /> <RateVolume data="[ { rate: 0.023, volume: 220 }, { rate: 0.028, volume: 160 }, { rate: 0.031, volume: 110 }, { rate: 0.036, volume: 66 }, { rate: 0.041, volume: 38 }, ]" format="{ style: "percent", maximumFractionDigits: 1 }" curve="step" title="Per-period step" width="220" height="26" /> </span> ``` ```tsx `" > <RateVolume data="[ { rate: 0.023, volume: 220 }, { rate: 0.041, volume: 38 }, ]" format="{ style: "percent", maximumFractionDigits: 1 }" volumeFormat="{ maximumFractionDigits: 0 }" locale="de-DE" title="Localized rate" width="180" height="26" /> ``` `format` and `volumeFormat` both take `Intl.NumberFormatOptions` and share the same `locale` — the rate label reads "4,1 %" and volumes group with a period ("3.800") under `de-DE`, matching that locale's own conventions rather than a hardcoded English format. ## Edge cases [#edge-cases] ```tsx `" > <RateVolume data="[ { rate: 0.02, volume: 200 }, { rate: Number.NaN, volume: 0 }, { rate: 0.03, volume: 180 }, ]" format="{ style: "percent", maximumFractionDigits: 0 }" title="Gap on zero volume" width="140" height="26" /> ``` ```tsx `"> <RateVolume data="[]" title="No periods yet" width="140" height="26" /> ``` A period with zero (or non-finite) volume renders no bar and no rate mark, and the line gaps across it instead of interpolating through a period nothing was measured on — the interactive entry announces that period as **"no events"** rather than a rate. With no data at all, the chart renders an empty root and the accessible name says **"No data."** ## Why this default [#why-this-default] The volume bars are muted and unlabeled because they answer "enough?", not "how many?". A rate on **zero** volume is undefined regardless of the input — the line breaks and no mark is drawn, because a rate nobody generated should never be plotted. `minVolume` makes a thin denominator visible right at the mark: below it the rate point renders hollow, a shape cue that survives forced-colors and print. ## Accessibility [#accessibility] The accessible name always pairs the rate with its volume — **"4.1% on 38 events (low volume); up from 2.3% across 5 periods."**. The interactive entry steps the periods and its live region never states a rate without the volume it stands on, announcing "no events" for a zero-volume period. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ rate; volume }[]` | Periods, oldest first — each a rate and the volume it was measured on. | | `minVolume` | `number` | Below it, the rate mark renders hollow — 'insufficient denominator'. | | `curve` | `"linear" \| "step"` | Step suits per-period aggregate rates. | | `volumeFormat` | `Intl.NumberFormatOptions \| (n) => string` | Volume has different units than rate; formatted separately. | | `unit` | `string` | Noun for the volume unit in the summary (default 'events'). | | `volumeDomain` | `[number, number]` | Volume (bar) domain — defaults to [0, max], zero-anchored. | | `label` | `"last" \| "none"` | Endpoint rate in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # RetentionCurve (/docs/charts/retention-curve) RetentionCurve answers "do they stay — and does the curve plateau?". It draws a **step** line (cohort periods are discrete) on a scale **locked to 0–100%** — the full range is the honest frame for a share, so the floor is never truncated to manufacture drama. When the curve flattens, a dotted plateau marker appears; a peer curve can ride behind as a subordinate ghost. ```tsx `" > <RetentionCurve data="[1, 0.72, 0.55, 0.47, 0.42, 0.4, 0.39, 0.385, 0.382, 0.38, 0.379, 0.378]" unit="week" label="last" title="W12 cohort" width="260" height="30" /> ``` ## Install [#install] ```tsx import { RetentionCurve } from "@microcharts/react/retention-curve"; <RetentionCurve data={cohort} unit="week" title="W12 cohort" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a cohort retention curve in a KPI card, your decay vs an industry benchmark, spotting whether retention plateaus (or keeps leaking). * **Avoid for** — a continuous signal (Sparkline) or one-number retention (Progress / Delta). ## Variants [#variants] ```tsx <RetentionCurve data={[1, 0.72, 0.55, 0.47, 0.42, 0.4, 0.39, 0.385, 0.382, 0.38]} curve="smooth" />`" > <span className="inline-flex flex-col gap-1.5"> <RetentionCurve data="[1, 0.72, 0.55, 0.47, 0.42, 0.4, 0.39, 0.385, 0.382, 0.38]" benchmark="[1, 0.6, 0.44, 0.37, 0.33, 0.3, 0.29, 0.285, 0.282, 0.28]" unit="week" title="vs industry" width="220" height="28" /> <RetentionCurve data="[1, 0.72, 0.55, 0.47, 0.42, 0.4, 0.39, 0.385, 0.382, 0.38]" curve="smooth" unit="week" title="smooth" width="220" height="28" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <RetentionCurve data="[1]" unit="week" title="Week zero only" width="140" height="26" /> ``` ```tsx `" > <RetentionCurve data="[100, 72, 55, 47, 42, 40, 39]" unit="week" title="Percent-scale input" width="180" height="26" /> ``` ```tsx `" > <RetentionCurve data="[1, 0.72, 0.55, 0.47, 0.42, 0.4, 0.39]" unit="week" label="last" locale="de-DE" title="Localized retention" width="180" height="26" /> ``` A single period is too short for plateau detection (the window needs at least four finite points) and renders as a single step with no visible line. `data` accepts either a 0–1 fraction or a 0–100 percent series — whichever the max value implies — so a raw percent export renders identically to its fraction form without a manual divide. With a `locale`, the percent label and every announced number follow that locale's own formatting. ## Why this default [#why-this-default] Step line plus the full 0–100% range, because retention is a discrete share, not a continuous signal — a smoothed curve implies between-period values that never existed, and a truncated floor exaggerates or hides the drop. The plateau marker appears **only** when the mean period-over-period change over the tail falls below half a point — never as decoration — and the benchmark stays a subordinate dashed ghost, never a second competing line. ## Accessibility [#accessibility] The accessible name states the final retention and, when detected, the plateau — **"38% retained after 10 weeks; curve plateaus from week 6."**. The interactive entry steps the periods and announces each period's retention alongside the benchmark's. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Fraction retained per period (0–1 or 0–100); period 0 is typically 1.0. | | `benchmark` | `number[]` | Peer/industry curve, drawn as a subordinate dashed ghost. | | `plateau` | `boolean` | Detect + mark a plateau (default true). | | `curve` | `"step" \| "smooth"` | Step (default — cohorts are discrete) or smooth (editorial). | | `unit` | `string` | Period noun for the summary (default 'period'). | | `label` | `"last" \| "none"` | Final retention in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # RubricStrip (/docs/charts/rubric-strip) RubricStrip answers "how did this thing score per criterion — with each criterion's importance visible — without a fake composite number?". Each bar's length is its score and its thickness is its weight share, so the things that matter most are literally the biggest marks. There is no total bar, and none may be added — the type exists to resist collapsing quality into one number. ```tsx `" > <RubricStrip data="[ { label: "Correctness", score: 0.92, weight: 3 }, { label: "Coverage", score: 0.78, weight: 2 }, { label: "Clarity", score: 0.65, weight: 1 }, { label: "Style", score: 0.41, weight: 1 }, ]" target="0.7" title="Model eval" width="240" height="44" /> ``` ## Install [#install] ```tsx import { RubricStrip } from "@microcharts/react/rubric-strip"; <RubricStrip data={[ { label: "Correctness", score: 0.92, weight: 3 }, { label: "Coverage", score: 0.78, weight: 2 }, { label: "Clarity", score: 0.65, weight: 1 }, { label: "Style", score: 0.41, weight: 1 }, ]} title="Model eval" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — model / code-review scorecards, weighted vendor comparison. * **Avoid for** — a single criterion (Bullet) or parts of a whole (SegmentedBar). ## Variants [#variants] ```tsx `" > <RubricStrip data="[ { label: "Lint", score: 1 }, { label: "Types", score: 1 }, { label: "Tests", score: 0.8 }, { label: "Docs", score: 0.5 }, ]" title="Checklist" width="240" height="44" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <RubricStrip data="[{ label: "Bonus", score: 2, weight: 1 }]" title="Clamped" width="200" height="16" /> ``` ```tsx `"> <RubricStrip data="[{ label: "Overall fit", score: 0.83 }]" title="Single criterion" width="200" height="16" /> ``` ## Why this default [#why-this-default] Weight-as-thickness keeps "importance" visible where a table hides it — a light criterion that scores well can't visually outweigh a heavy one that scores poorly. The summary names the extremes, never a weighted average, because the whole point is that a single number throws away the structure. A `target` draws one honest pass line across every row instead. ## Accessibility [#accessibility] The accessible name names the extremes — **"4 criteria; highest Lint (1), lowest Docs (0.5)."** The interactive entry roves the criteria, announcing each one's score and its weight share of the total (**"Coverage: 0.78, weight 29% of total."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label, score, weight? }[]` | Criteria; weights default equal. | | `target` | `number` | Pass target — one tick across all rows. | | `labels` | `boolean` | Criterion names in the left gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # RugStrip (/docs/charts/rug-strip) RugStrip answers "where do the raw observations actually sit?". Every tick is one real observation — no binning, no jitter, no thinning. Stacked duplicates darken (tiered opacity), and `markValue` tells the chart's strongest single story: one raw value against the field. ```tsx `" > <span className="text-lg"> {"Your offer sits "} <RugStrip data="[42, 48, 51, 53, 55, 58, 61, 63, 66, 71, 55, 52, 49, 58, 62, 75, 83]" markValue="78" title="Pay band" style="{ width: "7em", height: "0.9em" }" /> {" inside the band."} </span> ``` ## Install [#install] ```tsx import { RugStrip } from "@microcharts/react/rug-strip"; <RugStrip data={salaries} markValue={yourOffer} title="Pay band" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — "you are here" in a pay band, raw spread beside a stat, margin composition under a Sparkline. * **Avoid for** — more than \~400 observations (a rug promises raw marks and never downsamples; use HistogramStrip) or trends over time (Sparkline). ## Variants [#variants] ```tsx `"> <RugStrip data="[42, 48, 55, 58, 61, 66, 71, 75]" markValue="62" title="Field plus you" style="{ width: 140, height: 14 }" /> ``` ```tsx `" > <RugStrip data="[50, 50, 50, 50, 62, 71]" title="Duplicates" style="{ width: 140, height: 14 }" /> ``` ```tsx `"> <RugStrip data="[42, 48, 55, 61, 71]" orientation="vertical" title="Vertical rug" style="{ width: 14, height: 80 }" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <RugStrip data="[]" title="No observations" style="{ width: 140, height: 14 }" /> ``` Empty data draws a quiet centered axis line — not a blank hole — so the strip still reads as "a rug with nothing on it" rather than a layout gap. ```tsx `"> <RugStrip data="[52]" title="One observation" style="{ width: 140, height: 14 }" /> ``` A single value (or an all-equal field) has a zero-span domain; the tick renders at the strip's midpoint instead of dividing by zero. ```tsx `"> <RugStrip data="[42, 48, 55, 61, 71]" markValue="120" title="Above the field" style="{ width: 140, height: 14 }" /> ``` A `markValue` outside the observed domain clamps to the nearest edge — it never escapes the box or silently rescales the field around it. ## Why this default [#why-this-default] Ticks sit at 35% opacity — singles stay visible while stacks read as density. Because a browser paints one path's stroke as a single operation, coincident ticks are bucketed into opacity tiers (35% / 60% / 85%) rather than relying on overlap compositing that never happens. Regular ticks are inset one unit so the full-height accent highlight reads "taller" without escaping the box. ## Accessibility [#accessibility] The accessible name is the distribution — **"8 values from 42 to 75, median 59.5."** The interactive entry walks observations in sorted order and announces each with its rank: **"48 — 2nd of 17."** The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Raw observations — position = value. | | `markValue` | `number` | One value emphasized against the field. | | `orientation` | `"horizontal" \| "vertical"` | Vertical rugs sit beside distributions. | | `domain` | `[number, number]` | Fix the scale across rows (rugs mislead worst under per-row autoscale). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # SegmentedBar (/docs/charts/segmented-bar) SegmentedBar answers "what is this made of, and in what proportions?". Segments always sum to the full bar; past `maxSegments` the tail rolls into a labeled "Other" — nothing is silently dropped. A flat bar beats a donut of the same data at every size we ship. ```tsx <SegmentedBar data="[ { label: "Chrome", value: 620 }, { label: "Safari", value: 240 }, { label: "Firefox", value: 90 }, { label: "Edge", value: 30 }, { label: "Arc", value: 20 }, ]" title="Browser share" width="220" height="20" /> ``` ## Install [#install] ```tsx import { SegmentedBar } from "@microcharts/react/segmented-bar"; <SegmentedBar data={mix} title="Browser share" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — traffic mix per table row, composition in KPI cards. * **Avoid for** — precise cross-row comparison (MiniBar) or negative parts (Waterfall). ## Variants [#variants] ```tsx `" > <SegmentedBar data="[ { label: "Chrome", value: 620 }, { label: "Safari", value: 240 }, { label: "Firefox", value: 140 }, ]" title="With percents" width="220" height="20" /> ``` ```tsx `" > <SegmentedBar data="[ { label: "Firefox", value: 90 }, { label: "Chrome", value: 620 }, { label: "Safari", value: 240 }, ]" order="desc" title="Ranked" width="220" height="20" /> ``` ```tsx `" > <SegmentedBar data="[ { label: "Chrome", value: 12400 }, { label: "Safari", value: 6200 }, ]" label="value" locale="de-DE" title="Localized values" width="220" height="20" /> ``` `label="value"` follows `format`/`locale` — 12400 reads "12.400" under `de-DE` rather than the English "12,400". `label="percent"` is unaffected: the largest-remainder shares are always plain integers, never locale-formatted, because a percent point is the same everywhere. ## Edge cases [#edge-cases] ```tsx `" > <SegmentedBar data="[ { label: "Chrome", value: 620 }, { label: "Safari", value: 240 }, { label: "Firefox", value: 90 }, { label: "Edge", value: 30 }, { label: "Arc", value: 12 }, { label: "Brave", value: 8 }, ]" label="percent" title="Six sources, five segments" width="220" height="20" /> ``` ```tsx `"> <SegmentedBar data="[{ label: "Chrome", value: 1 }]" label="percent" title="Single category" width="100" height="20" /> ``` Past `maxSegments` (default 5) the smallest categories merge into a labeled "Other" — nothing is dropped, only rolled up, and the interactive entry announces its member count. A single category still renders as one full-width, 100% segment rather than a special-cased bare bar. Negative values can't exist in a part-to-whole, so they're excluded from the bar entirely (not clamped to zero) and the component logs a dev warning steering toward Waterfall. ## Why this default [#why-this-default] Data order is the default — inherent sequences (funnel-like stages, weekday mixes) carry meaning that ranking destroys. Summary percents use largest-remainder rounding so they always sum to exactly 100; negative values are excluded with a dev warning (a part-to-whole cannot contain negative parts — use Waterfall). ## Accessibility [#accessibility] The accessible name is the full composition — **"Chrome 62%, Safari 24%, Firefox 9%, Edge 3%, Other 2%."** The interactive entry roves segments; the Other segment announces its member count (**"Other: 2%, 2 categories."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value }[]` | Parts of the whole. | | `maxSegments` | `number` | Rollup threshold — the tail becomes a labeled Other. | | `order` | `"data" \| "desc"` | Preserve inherent sequences or rank the composition. | | `label` | `"none" \| "percent" \| "value"` | Centered per segment (deterministic drop-out; default percent). | | `colors` | `string[]` | Per-segment colours, cycled; overrides --mc-cat-N. Other stays neutral. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Seismogram (/docs/charts/seismogram) Seismogram answers "when did things happen, and how hard?". Ticks read as a seismograph trace — centered on a midline and flaring symmetrically: presence is density texture, length is intensity. Long series collapse via max-per-bucket only — the spike is the chart's whole job, so it always survives, and the summary is always computed from the raw values, never the buckets. ```tsx `" > <Seismogram data="[1, 2, 1, 3, 2, 6, 2, 1, 0, 2, 1, 4, 9, 3, 1, 2, 0, 1, 3, 2, 7, 2, 1, 0, 2, 1, 5, 11, 3, 1]" title="Error bursts" width="240" height="36" /> ``` ## Install [#install] ```tsx import { Seismogram } from "@microcharts/react/seismogram"; <Seismogram data={burstsPerMinute} title="Error bursts" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — error bursts per service, alert density, activity texture in rows. * **Avoid for** — level tracking (Sparkline) or labeled events (EventTimeline). ## Variants [#variants] ```tsx `" > <Seismogram data="[1, 0, 2, 1, 3, 0, 1, 2, 0, 1, 1, 0, 2, 1, 3, 1, 0, 1, 2, 1]" mode="barcode" title="Deploys" width="180" height="22" /> ``` ```tsx `" > <Seismogram data="[3, -1, 4, -2, 1, 5, -3, 2, -1, 4, -2, 6, -4, 1, -2, 3, -1, 2]" positive="up" title="Net flow shocks" width="200" height="30" /> ``` ```tsx `" > <Seismogram data="[1, 2, 1, 3, 2, 6, 2, 1, 0, 2, 1, 4, 9, 3, 1, 2, 0, 1, 3, 2, 7, 2, 1, 0, 2, 1, 5, 11, 3, 1, 2, 1]" anomaly="6" title="Error bursts" width="240" height="36" /> ``` ```tsx `" > <Seismogram data="[3, -1, 4, -2, 12500, 5, -3, 2, -1, 4]" positive="up" format="{ maximumFractionDigits: 0 }" locale="de-DE" title="Localized magnitudes" width="200" height="30" /> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, the accessible summary's peak number follows that locale's own grouping ("12.500" in German, not "12,500"). Tick positions and lengths are unaffected; only the announced peak is localized. ## Edge cases [#edge-cases] ```tsx `" > <Seismogram data="[0, 0, 0, 0, 0, 0]" title="Quiet" width="160" height="20" /> ``` ```tsx (i === 210 ? 9 : i % 17 === 0 ? 2 : 0))} />`" > <Seismogram data="Array.from({ length: 300 }, (_, i) => (i === 210 ? 9 : i % 17 === 0 ? 2 : 0))" title="Long history" width="160" height="24" /> ``` ## Why this default [#why-this-default] A centered seismograph trace over bottom-anchored bars: the symmetric flare reads as event intensity rather than inviting the bar-to-bar magnitude comparison the strip is too small to support — and it stays visually distinct from SparkBar. Barcode mode is documented as presence-only — a uniform tick is not intensity. `anomaly` flags spikes at or above a threshold in the alert token; the flag is redundant with tick length, never color alone. A quiet strip renders its baseline at rest, never a blank hole. ## Accessibility [#accessibility] The accessible name counts the events — **"29 events, peak 11."**, or **"No events."** for a quiet strip. The interactive entry steps slots with position readouts ("Point 2 of 5: 3."), announces quiet slots as "no data", and Home/End jump to the first/last event. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | Per-slot event intensity; 0/null = quiet. | | `mode` | `"intensity" \| "barcode"` | Barcode collapses heights — pure occurrence density. | | `positive` | `"up" \| "down"` | Polarity coloring of signed ticks. | | `anomaly` | `number` | Flag spikes: \|v\| ≥ threshold flares in the alert token. | | `domain` | `[number, number]` | Fixed intensity scale across rows. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # ShiftHistogram (/docs/charts/shift-histogram) ShiftHistogram answers "did the fix actually change the distribution?". It mirrors two histograms around a center line — **before** upward (muted), **after** downward (accent) — on **shared bin edges**, with the median shift as the precise takeaway. Bar heights are per-side proportions on one shared scale, so a bigger sample on one side can't fake a shift. The mirror carries **identity**, not valence (up isn't "good") — that's the whole point of the symmetry. ```tsx <ShiftHistogram data="{ before: Array.from({ length: 100 }, (_, i) => 120 + (i % 40) - 20), after: Array.from({ length: 100 }, (_, i) => 96 + (i % 40) - 20), }" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" title="The fix" width="260" height="30" /> ``` ## Install [#install] ```tsx import { ShiftHistogram } from "@microcharts/react/shift-histogram"; <ShiftHistogram data={{ before, after }} title="The fix" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a "the fix, proven" read in a KPI card, before/after distributions in an experiments table, showing a change is real (not just a mean move). * **Avoid for** — a single distribution (HistogramStrip) or two labelled arms (ABStrips). ## Variants [#variants] ```tsx 120 + (i % 40) - 20); const after = Array.from({ length: 100 }, (_, i) => 96 + (i % 40) - 20); <ShiftHistogram data={{ before, after }} mode="overlay" /> <ShiftHistogram data={{ before, after: before }} />`" > <span className="inline-flex flex-col gap-2"> <ShiftHistogram data="{ before: Array.from({ length: 100 }, (_, i) => 120 + (i % 40) - 20), after: Array.from({ length: 100 }, (_, i) => 96 + (i % 40) - 20), }" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" mode="overlay" title="Overlay" width="240" height="26" /> <ShiftHistogram data="{ before: Array.from({ length: 100 }, (_, i) => 120 + (i % 40) - 20), after: Array.from({ length: 100 }, (_, i) => 120 + (i % 40) - 20), }" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" title="No shift" width="240" height="26" /> </span> ``` ```tsx `" > <ShiftHistogram data="{ before: [12000, 12400, 12800], after: [9600, 10000, 10400] }" locale="de-DE" title="Localized medians" width="200" height="26" /> ``` The median shift label and accessible summary follow `format`/`locale` — the before median above reads "12.400" under `de-DE` rather than the English "12,400". ## Edge cases [#edge-cases] ```tsx 120 + (i % 40) - 20); <ShiftHistogram data={{ before, after: [] }} format={(n) => Math.round(n) + " ms"} title="Awaiting after sample" />`" > <ShiftHistogram data="{ before: Array.from({ length: 100 }, (_, i) => 120 + (i % 40) - 20), after: [], }" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" title="Awaiting after sample" width="240" height="26" /> ``` ```tsx `"> <ShiftHistogram data="{ before: [], after: [] }" title="No data yet" width="200" height="26" /> ``` With one side empty the chart still renders the populated side's bins alone, and the summary names the gap directly — **"Median 116 ms; no after sample."** — never a fabricated shift. With both sides empty nothing is plottable and the accessible name says **"No data."** ## Why this default [#why-this-default] Mirror, because before/after symmetry makes the shift a visible displacement. The only normalization allowed is per-side proportions — each side's counts over its own n — on one shared height scale, so unequal sample sizes never fake a shift, and the rule is stated. The bins are shared across both sides always, and the medians are never smoothed or trimmed. Side identity rides on position (up vs before, down vs after) so it survives grayscale and forced-colors; the summary names the direction and, when the sample sizes differ, carries both. ## Accessibility [#accessibility] The accessible name states the median shift plainly — **"Median fell from 116 ms to 92 ms."** — appending "On N / M samples" when the sizes differ. The interactive entry steps the bins and announces each bin's before/after proportions; **M** jumps to the two median bins. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ before: number[]; after: number[] }` | The two samples — raw observations, shared bin edges are derived. | | `bins` | `number` | Shared bin count (default auto, Sturges capped at 12). | | `mode` | `"mirror" \| "overlay"` | Mirror (default) or after-as-outline over before fill. | | `seriesLabels` | `[string, string]` | Side identities for the summary (default ['before', 'after']). | | `label` | `"shift" \| "none"` | Signed median shift in a right gutter. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Slope (/docs/charts/slope) Slope answers "who rose and who fell between two moments — and did the order change?". Lines stay neutral until you declare `positive`: a rank change is not automatically good or bad. Both columns share one y-domain — per-column normalization would fake convergence. ```tsx `" > <Slope data="[ { label: "East", from: 40, to: 47 }, { label: "West", from: 55, to: 41 }, { label: "South", from: 30, to: 33 }, ]" title="Before vs after" width="130" height="90" /> ``` ## Install [#install] ```tsx import { Slope } from "@microcharts/react/slope"; <Slope data={cohorts} title="Before vs after" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — before/after experiments, rank shuffles, two-moment comparisons. * **Avoid for** — the path between the moments (Sparkline) or more than 7 categories. ## Variants [#variants] ```tsx <Slope data={rows} positive="up" highlight="West" />`" > <span className="inline-flex gap-6"> <Slope data="[ { label: "East", from: 40, to: 47 }, { label: "West", from: 55, to: 41 }, { label: "Mid", from: 20, to: 35 }, ]" label="both" title="Labeled" width="180" height="100" /> <Slope data="[ { label: "East", from: 40, to: 47 }, { label: "West", from: 55, to: 41 }, { label: "Mid", from: 20, to: 35 }, ]" positive="up" highlight="West" title="Valence" width="130" height="90" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `" > <Slope data="[ { label: "East", from: 40, to: 47 }, { label: "New", from: NaN, to: 41 }, ]" title="New entrant" width="130" height="70" /> ``` ```tsx `"> <Slope data="[{ label: "East", from: 40, to: 47 }]" title="One category" width="90" height="60" /> ``` ```tsx `" > <Slope data="[ { label: "East", from: 4000, to: 4700 }, { label: "West", from: 5500, to: 4100 }, ]" label="both" locale="de-DE" title="Localized values" width="150" height="90" /> ``` A row missing one side (`from` or `to` as `NaN`) draws a short dashed stub toward the end it does have, rather than a full line — there's no second point to connect to, so nothing is interpolated. With a `locale`, both column labels and the announced values follow that locale's own grouping. ## Why this default [#why-this-default] A two-point line implies nothing about the path between — the docs steer to Sparkline when the journey matters. End labels drop deterministically, never by measurement: when the rows are denser than the label font (height ÷ count), and when the reserved label gutters would squeeze the two columns under \~35% of the width — in which case the reclaimed room goes back to the lines. Endpoints that would collide inside a column are nudged apart to a full glyph pitch instead of overlapping. A missing end renders a dashed stub and is announced "incomplete", never interpolated. ## Accessibility [#accessibility] The accessible name counts directions and leads with the biggest mover — **"3 categories: 2 up, 1 down. Largest change Mid, up 75%."** The interactive entry finds the nearest line under the pointer and roves categories ordered by their after-value, announcing each slope (**"East: 40 to 47, up 18%."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; from; to }[]` | Two aligned moments per category. | | `label` | `"none" \| "value" \| "label" \| "both"` | End labels; dropped deterministically when rows collide. | | `highlight` | `number \| string` | The one-vs-field editorial read. | | `positive` | `"up" \| "down"` | Direction valence; unset = neutral ink. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # SparkBar (/docs/charts/sparkbar) SparkBar renders discrete values as compact bars from a zero baseline. In `winloss` mode it collapses each value to its sign — a streak you can read at a glance: wins above the mid-line, losses below, and a tie (`0`) as a thin neutral dash on it. ```tsx <SparkBar data="[4, 6, 2, 8, 5, 9]" width="120" height="32" title="Deploys per day" /> ``` ## Install [#install] ```tsx import { SparkBar } from "@microcharts/react/sparkbar"; <SparkBar data={[4, 6, 2, 8, 5, 9]} title="Deploys per day" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — discrete magnitudes, win–loss streaks, period-over-period counts. * **Avoid for** — a continuous trend shape (use [Sparkline](/docs/charts/sparkline)) or hundreds of points, where bars become noise. ## Sizing [#sizing] `width` and `height` are viewBox units that also set the rendered pixel box. Omit them and drive the width from CSS for a chart that fills its container — the viewBox keeps the aspect ratio. ## Variants [#variants] ```tsx `"> <SparkBar data="[4, 6, 2, 8, 5, 9]" width="130" height="32" title="Magnitude" /> ``` ```tsx `"> <SparkBar data="[1, -1, 1, 1, -1, 1, -1]" width="130" height="32" mode="winloss" title="Win–loss streak" /> ``` ```tsx `" > <SparkBar data="[1, -1, 0, 1, 0, -1, 1]" width="130" height="32" mode="winloss" title="Win–loss–tie streak" /> ``` ```tsx `"> <SparkBar data="[4, 6, 2, 8, 5, 9]" width="130" height="32" label="last" title="With endpoint label" /> ``` ```tsx `"> <SparkBar data="[4200, 6100, 2800, 8600]" width="130" height="32" label="last" locale="de-DE" title="Localized" /> ``` The endpoint label and accessible summary both follow `format`/`locale` — 8600 reads "8.600" under `de-DE` rather than the English "8,600". ## Edge cases [#edge-cases] ```tsx `"> <SparkBar data="[]" title="No deploys yet" width="100" height="32" /> ``` ```tsx `"> <SparkBar data="[6]" title="One deploy" width="40" height="32" /> ``` An empty series renders no bars and an accessible name that says so, rather than a flat or invented baseline. A single value still renders as one zero-anchored bar — `winloss` mode treats it the same way a longer streak would: a lone win, loss, or tie. ## Why this default [#why-this-default] Bars, not a line, because SparkBar's job is discrete magnitudes — deploy counts, daily totals — where each period is its own thing, not a sampled point on a continuous curve. Zero-anchored always: a bar whose length doesn't start at zero misstates its magnitude. `winloss` mode goes further and discards magnitude entirely on purpose, collapsing each value to a three-state streak (win above the mid-line, loss below, tie a thin dash on it) because for a streak, sign is the whole story and a magnitude axis would just be noise. Sign is doubled by position AND color everywhere signed data appears, so direction survives forced-colors and never depends on color alone. In `bar` mode the endpoint bar takes the accent — "where did it land" is usually the first question a run of counts answers; in `winloss` mode it keeps its win/loss/tie color instead, because there the sign is what matters at every position, endpoint included. ## Accessibility [#accessibility] Announced from the data — the example above reads: > Deploys per day. Trending up 125%. Range 2 to 9. Last value 9. Sign is doubled by position (above or below the baseline), never by color alone, so the chart survives forced-colors and color-blind viewing. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Values; negatives dip below the baseline. | | `mode` | `"bar" \| "winloss"` | Magnitude bars, or a win/loss/tie streak (sign only). | | `gap` | `number` | Empty fraction of each slot (0–0.9). | | `label` | `"none" \| "last"` | Direct endpoint value label. | | `positive` | `"up" \| "down"` | "up" (default); "down" flips which sign is good. | | `title` | `string` | Accessible name; joins the auto summary. | | `summary` | `string \| false` | Override or disable the auto summary. | | `locale` | `string \| string[]` | BCP 47 locale(s) for the endpoint label and summary. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Sparkline (/docs/charts/sparkline) Sparkline draws a compact trend over ordered values. Reach for it when direction and shape matter more than exact points — inline in a sentence, inside a table cell, or as the quiet backbone of a KPI card. ```tsx <Sparkline data="[3, 5, 4, 8, 6, 9]" width="120" height="32" title="Weekly revenue" /> ``` ## Install [#install] ```tsx import { Sparkline } from "@microcharts/react/sparkline"; <Sparkline data={[3, 5, 4, 8, 6, 9]} title="Weekly revenue" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — an inline trend, a table-cell trend, a KPI sparkline, dense dashboards. * **Avoid for** — part-to-whole comparisons or reading exact category values. Use [SparkBar](/docs/charts/sparkbar) for discrete magnitudes, or [Bullet](/docs/charts/bullet) for a value against a target. ## Sizing [#sizing] `width` and `height` are viewBox units that also set the rendered pixel box. Omit them and drive the width from CSS for a chart that fills its container — the viewBox keeps the aspect ratio. ## Variants [#variants] Shape, fill, a normal-range band, and dots are all props — same data, different read. Flip any of them to the Code tab. ```tsx `"> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="120" height="32" curve="smooth" title="Smooth curve" /> ``` ```tsx `"> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="120" height="32" title="Filled area" /> ``` ```tsx `"> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="120" height="32" band="[4, 8]" title="Normal-range band" /> ``` ```tsx `"> <Sparkline data="[3, 5, 4, 8, 6, 9]" width="130" height="32" dots="minmax" label="last" title="Min/max dots" /> ``` ```tsx `" > <Sparkline data="[3, 5, 4, 8, 6, 9, 2, 7]" width="130" height="36" dots="minmax" label="minmax" title="Extremes labelled" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <Sparkline data="[3, 5, null, null, 6, 9, 4, 7]" width="130" height="32" title="Series with gaps" /> ``` ```tsx `"> <Sparkline data="[7]" width="80" height="32" title="One value" /> ``` ```tsx `"> <Sparkline data="[5, 5, 5, 5, 5, 5]" width="130" height="32" title="Flat series" /> ``` A `null` means "no measurement here" — the line breaks at the gap and never interpolates across it, so an outage can't masquerade as a smooth trend. A single point has no line to draw; it sits centered in the plot, visible as the default endpoint dot. An all-equal series renders on the vertical mid-line — a zero-span domain maps to the middle of the range, so flat data reads as level, not as bottomed-out. Past `maxPoints` (default 200) the drawn line decimates to a min/max-preserving envelope: every spike keeps its true position and height, gaps stay gaps, and the summary, dots, and hover values still come from the raw data — only the path gets lighter. Pass `maxPoints={Infinity}` to opt out. ```tsx i === 1500 ? 98 : 50 + Math.sin(i / 40) * 24 + ((i * 13) % 7), )} />`" > <Sparkline data="Array.from({ length: 2000 }, (_, i) => (i === 1500 ? 98 : 50 + Math.sin(i / 40) * 24 + ((i * 13) % 7)))" width="220" height="40" title="Two thousand points, one spike" /> ``` ## Four homes [#four-homes] The same chart, sized for four real contexts. Each preview is the public component plus `styles.css` — no docs-only wrappers. Sentence placements use `mc-inline`; see [Composition](/docs/composition) and [Sizing](/docs/sizing). ## Why this default [#why-this-default] A bare line plus one accent dot on the last point — no fill, no band, no min/max dots. The shape of the series is the whole story until you ask for more, and the endpoint dot marks where "now" is. Min/max dots, fill, and the band are opt-in because at word size they compete with the line for the same few pixels; adding them by default would make every sparkline noisier for the common case that only needs direction and range. Long series decimate to a min/max-preserving envelope rather than a naive stride sample, so a single spike at point 1,500 of 2,000 still shows up — silently dropping it would be the more common bug in a naive implementation, and a chart that hides its own spikes is dishonest by construction. ## Accessibility [#accessibility] By default the chart is an `img` whose accessible name is generated from the data. The example above is announced as: > Weekly revenue. Trending up 200%. Range 3 to 9. Last value 9. Pass a `title` to name it, or `summary={false}` to make it decorative when the surrounding text already says what it shows. The interactive entry adds a polite live region that reads each focused point as you arrow through it. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | The series. null/NaN are gaps. | | `curve` | `"linear" \| "smooth" \| "step"` | Line shape. | | `fill` | `boolean` | Zero-anchored area under the line. | | `band` | `[number, number]` | Constant normal-range band. | | `dots` | `"auto" \| "minmax" \| "none"` | Endpoint or min/max dots. | | `label` | `"none" \| "last" \| "minmax"` | Direct value labels: endpoint, or the extremes. | | `maxPoints` | `number` | Line-point cap (default 200); longer series decimate min/max-preserving. | | `title` | `string` | Accessible name; joins the auto summary. | | `summary` | `string \| false` | Override or disable the auto summary. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # SpiralYear (/docs/charts/spiral-year) SpiralYear answers "how did the year breathe?" It winds a calendar series onto an Archimedean spiral: the angle is the position in the year (January at 12 o'clock, running clockwise) and each turn outward is the next year. The value becomes a five-step opacity, so busy stretches read as darker arcs of the spiral. This is a **pattern instrument** — opacity is the weakest ordered channel, so for an exact day's value reach for `ActivityGrid` or `HeatStrip`. ```tsx <SpiralYear data="Array.from({ length: 52 }, (_, i) => { const s = Math.round(200 + 140 * Math.sin(((i - 8) / 52) * Math.PI * 2)); return i === 29 ? 480 : s; })" title="Seasonality" size="80" /> ``` ## Install [#install] ```tsx import { SpiralYear } from "@microcharts/react/spiral-year"; <SpiralYear data={byWeek} title="Seasonality" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — the seasonal shape of a year at a glance, spotting a busy season or a quiet stretch, or a compact "the year in one square". * **Avoid for** — reading an exact day's value (`ActivityGrid` / `HeatStrip`), a non-cyclic trend (`Sparkline`), or more than about three years. ## Variants [#variants] ```tsx { const s = Math.round(200 + 140 * Math.sin(((i - 8) / 52) * Math.PI * 2)); return i === 29 ? 480 : s; // a summer peak in week 30 }); <SpiralYear data={byWeek} mark="arc" /> <SpiralYear data={byWeek} steps={3} />`" > <span className="inline-flex gap-6 items-center"> <SpiralYear data="Array.from({ length: 52 }, (_, i) => { const s = Math.round(200 + 140 * Math.sin(((i - 8) / 52) * Math.PI * 2)); return i === 29 ? 480 : s; })" mark="arc" size="64" summary="false" /> <SpiralYear data="Array.from({ length: 52 }, (_, i) => { const s = Math.round(200 + 140 * Math.sin(((i - 8) / 52) * Math.PI * 2)); return i === 29 ? 480 : s; })" steps="3" size="56" summary="false" /> </span> ``` `locale` doesn't change any in-chart mark — opacity steps carry the value, never a printed number — but it does localize the peak and low values named in the accessible summary: ```tsx { const s = Math.round(200 + 140 * Math.sin(((i - 8) / 52) * Math.PI * 2)); return i === 29 ? 1480 : s; }); <SpiralYear data={byWeek} locale="de-DE" />`" > <SpiralYear data="Array.from({ length: 52 }, (_, i) => { const s = Math.round(200 + 140 * Math.sin(((i - 8) / 52) * Math.PI * 2)); return i === 29 ? 1480 : s; })" locale="de-DE" title="Localized summary" size="64" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <SpiralYear data="[80, 120, null, 90, 140]" title="With a gap" size="56" /> ``` ```tsx `"> <SpiralYear data="[]" title="Empty" size="56" /> ``` ## Why this default [#why-this-default] Month ticks are on by default because without a temporal anchor the spiral is just texture — the ticks are what make "when" readable. Five steps is the ceiling: ordered opacity supports about five discriminable levels, and more would be false precision. The spiral **radius encodes time only, never value** — an outer mark is simply a later date, not a bigger number. Two adjacent turns place different years at the same angle; that radial adjacency is calendar alignment, not similarity, and the chart never asks you to compare across it. A `null` day leaves a gap in the spiral, distinct from a faint step-one mark, because missing is not the same as low. ## Accessibility [#accessibility] The accessible name states the count, the peak, and the low — **"52 weeks; peak 1.480 in week 30, low in week 48."** (the `de-DE` localized demo). The interactive entry lets you arrow along the spiral chronologically, each mark announced with its period and value through a polite live region. Because the channel is ordinal opacity, the docs and summary steer any exact read to `ActivityGrid`. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(number \| null)[]` | One value per day or week (cadence inferred from length). | | `cadence` | `"day" \| "week"` | Data cadence; inferred from length (≈52 → week, else day) when omitted. | | `startDate` | `string` | ISO date anchoring index 0 to a calendar angle. | | `steps` | `3 \| 5` | Opacity quantization (default 5). | | `monthTicks` | `boolean` | Faint radial month ticks (default true). | | `mark` | `"dot" \| "arc"` | Dots (default) or short arc segments. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # SpreadBand (/docs/charts/spread-band) SpreadBand answers "which of two series leads, by how much, and since when?" The signed gap between a subject and its reference is filled and split at every crossing, so who is ahead and when it last flipped both read at a glance. The reference whispers: dashed, thinner, neutral — direction is carried by the fill sign and the text, never color alone. ```tsx <SpreadBand data="[ { a: 8, b: 12 }, { a: 9, b: 12 }, { a: 11, b: 13 }, { a: 12, b: 13 }, { a: 14, b: 13 }, { a: 15, b: 14 }, { a: 17, b: 14 }, { a: 18, b: 14 }, { a: 20, b: 15 }, { a: 21, b: 15 }, { a: 23, b: 16 }, { a: 24, b: 16 }, ]" seriesLabels="["Organic", "Paid"]" title="Organic vs paid" width="220" height="30" /> ``` ## Install [#install] ```tsx import { SpreadBand } from "@microcharts/react/spread-band"; <SpreadBand data={pairs} seriesLabels={["Organic", "Paid"]} title="Organic vs paid" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — lead-vs-reference in KPI cards, actual-vs-plan where the flip matters. * **Avoid for** — 3+ series (SparkGroup), or unpaired series / different units (never dual axes). ## Variants [#variants] ```tsx `" > <SpreadBand data="[ { a: 8, b: 12 }, { a: 12, b: 13 }, { a: 14, b: 13 }, { a: 17, b: 14 }, { a: 20, b: 15 }, { a: 24, b: 16 }, ]" seriesLabels="["Organic", "Paid"]" label="none" title="No gutter label" width="220" height="30" /> ``` ```tsx `" > <SpreadBand data="[ { a: 18, b: 12 }, { a: 16, b: 12 }, { a: 14, b: 13 }, { a: 11, b: 13 }, { a: 9, b: 14 }, { a: 8, b: 14 }, ]" seriesLabels="["Latency", "Budget"]" positive="down" title="Lower is better" width="220" height="30" /> ``` ```tsx `" > <SpreadBand data="[ { a: 8000, b: 12000 }, { a: 9000, b: 12000 }, { a: 11000, b: 13000 }, { a: 12000, b: 13000 }, { a: 14000, b: 13000 }, { a: 15000, b: 14000 }, { a: 17000, b: 14000 }, { a: 18000, b: 14000 }, { a: 20000, b: 15000 }, { a: 21000, b: 15000 }, { a: 23000, b: 16000 }, { a: 24000, b: 16000 }, ]" seriesLabels="["Organic", "Paid"]" locale="de-DE" title="Localized values" width="230" height="30" /> ``` The gutter label and the hover readout follow the `locale`'s grouping — the German build reads the current gap as **+8.000** and the summary as "Organic leads Paid by 8.000; last crossed at point 5." ## Edge cases [#edge-cases] ```tsx `" > <SpreadBand data="[ { a: 10, b: 5 }, { a: 12, b: 6 }, { a: 14, b: 7 }, ]" seriesLabels="["A", "B"]" title="Never crosses" width="200" height="30" /> ``` ```tsx `" > <SpreadBand data="[ { a: 12, b: 12 }, { a: 15, b: 15 }, { a: 14, b: 14 }, { a: 18, b: 18 }, ]" title="Level throughout" width="200" height="30" /> ``` ```tsx `"> <SpreadBand data="[ { a: 12, b: 10 }, { a: 14, b: null }, { a: 13, b: 12 }, { a: 16, b: 13 }, ]" seriesLabels="["A", "B"]" title="Shared gaps" width="200" height="30" /> ``` A `null` in either series is a gap in **both** — the gap is undefined where a reading is missing, so the fill and both lines break at that index rather than inventing a value. Identical series read "The two series are level — no gap." and a subject that never falls behind reports "never crossed." ## Why this default [#why-this-default] One shared domain across both series — comparability is the whole point, so there are no dual axes and no per-series normalization. The gap is filled and split exactly at the interpolated crossings, so the eye lands on the flip without hunting. The reference whispers and the leader's sign is stated in text, so direction never rides on color alone. ## Accessibility [#accessibility] The accessible name states the lead, the current gap, and where the lines last crossed — **"Organic leads Paid by 8; last crossed at point 3."** Identical series read "The two series are level — no gap." The interactive entry announces the lead at each point (**"Point 12 of 12: Organic +8 over Paid."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ a: number \| null; b: number \| null }[]` | Paired readings — a is the subject, b the reference. | | `seriesLabels` | `[string, string]` | Names the two series in the summary and label. | | `positive` | `"up" \| "down"` | Which lead is the good valence; down flips the fill colors. | | `label` | `"gap" \| "none"` | Current signed gap in a right gutter (default gap). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # SproutRow (/docs/charts/sprout-row) SproutRow answers "how mature or healthy is each item in a small set?" Each item is one of four growth stages — **seed → sprout → leaf → bloom** — and the glyph height is strictly monotonic, so taller always means further along and the ordering reads without the legend. The stages are discrete and there are exactly four; there are no half-stages, because a growth metaphor must not fake continuity. ```tsx <SproutRow data="[ { label: "Acme", value: 3 }, { label: "Beta", value: 2 }, { label: "Gamma", value: 3 }, { label: "Delta", value: 1 }, { label: "Echo", value: 0 }, { label: "Foxtrot", value: 2 }, ]" title="Account health" height="30" step="24" /> ``` The key, shown once: **seed → sprout → leaf → bloom**. ## Install [#install] ```tsx import { SproutRow } from "@microcharts/react/sprout-row"; <SproutRow data={accounts} title="Account health" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — account or project maturity across a small set, a health column in a portfolio table, or per-item lifecycle in a KPI card. * **Avoid for** — continuous values (MiniBar), trends (Sparkline), or more than about twelve items. ## Variants [#variants] ```tsx <SproutRow data={[{ label: "A", value: 2 }, { label: "B", value: null }, { label: "C", value: 0 }]} />`" > <span className="inline-flex gap-6 items-center"> <SproutRow data="[ { label: "A", value: 0 }, { label: "B", value: 1 }, { label: "C", value: 2 }, { label: "D", value: 3 }, ]" label="value" height="26" step="20" /> <SproutRow data="[ { label: "A", value: 2 }, { label: "B", value: null }, { label: "C", value: 0 }, ]" height="24" step="22" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <SproutRow data="[]" title="No accounts" height="20" step="20" /> ``` ```tsx `"> <SproutRow data="[ { label: "A", value: 2 }, { label: "B", value: null }, ]" title="One account missing" height="20" step="20" /> ``` ```tsx `"> <SproutRow data="[ { label: "A", value: -3 }, { label: "B", value: 12 }, ]" title="Clamped stages" height="20" step="20" /> ``` Empty data draws just the frame. A `null` value renders only the soil tick — visibly distinct from a seed, which is stage 0 and gets its own glyph. Values outside `[0, 3]` round and clamp to the nearest real stage (seed or bloom) rather than drawing an out-of-bounds or fractional glyph. ## Why this default [#why-this-default] Labels are off by default because the row usually sits beside its own row label, and at micro scale the glyphs alone carry the ordering. The one-line key — seed → sprout → leaf → bloom — appears once above the demos, and after that the height does the work. A `null` value is a real gap: it draws only the soil tick, distinct from a seed, because "no data yet" is not "just planted". Presets recolor the glyphs but never reshape a stage; the four stages are fixed and never interpolated. ## Accessibility [#accessibility] The accessible name summarizes the row — **"4 items; 1 at bloom, 1 at seed."** The interactive entry roves the items with ←/→ (or hover), announcing each as **"Acme: bloom, stage 4 of 4."** — the stage name plus a 1-of-4 index — and reads "…: no data." for a missing item. A ring lifts the focused glyph. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label, value }[]` | value = stage 0–3. | | `labels` | `boolean` | Category labels under the slots. | | `label` | `"none" \| "value"` | Print the stage number above each glyph. | | `step` | `number` | Horizontal spacing between glyph slots (default 16; widens for labels). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # StackedArea (/docs/charts/stacked-area) StackedArea answers "how is the composition shifting over time?" Layer thickness is share; the stack always sums to 100%. Three series is the hard cap — beyond that, thickness at 16 px stops being readable. ```tsx <StackedArea data="[ { label: "Mobile", values: [30, 34, 36, 40, 44, 47, 52, 56, 58, 60, 63, 66] }, { label: "Web", values: [50, 48, 47, 45, 42, 41, 38, 36, 35, 33, 32, 30] }, { label: "API", values: [20, 18, 17, 15, 14, 12, 10, 8, 7, 7, 5, 4] }, ]" title="Traffic mix" width="220" height="30" /> ``` ## Install [#install] ```tsx import { StackedArea } from "@microcharts/react/stacked-area"; <StackedArea data={mix} title="Traffic mix" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — traffic/revenue mix in KPI cards, share-shift stories in sentences. * **Avoid for** — 4+ series, or exact values over time (SparkGroup of Sparklines). ## Variants [#variants] ```tsx <StackedArea data={mix} order="asc" /> <StackedArea data={mix} locale="de-DE" label="last" />`" > <span className="inline-flex flex-col gap-3"> <StackedArea data="[ { label: "Mobile", values: [30, 34, 36, 40, 44, 47, 52, 56, 58, 60, 63, 66] }, { label: "Web", values: [50, 48, 47, 45, 42, 41, 38, 36, 35, 33, 32, 30] }, { label: "API", values: [20, 18, 17, 15, 14, 12, 10, 8, 7, 7, 5, 4] }, ]" mode="ridge" title="Ridge skin" width="220" height="30" /> <StackedArea data="[ { label: "Mobile", values: [30, 34, 36, 40, 44, 47, 52, 56, 58, 60, 63, 66] }, { label: "Web", values: [50, 48, 47, 45, 42, 41, 38, 36, 35, 33, 32, 30] }, { label: "API", values: [20, 18, 17, 15, 14, 12, 10, 8, 7, 7, 5, 4] }, ]" order="asc" title="Ascending order" width="220" height="30" /> <StackedArea data="[ { label: "Mobile", values: [30, 34, 36, 40, 44, 47, 52, 56, 58, 60, 63, 66] }, { label: "Web", values: [50, 48, 47, 45, 42, 41, 38, 36, 35, 33, 32, 30] }, { label: "API", values: [20, 18, 17, 15, 14, 12, 10, 8, 7, 7, 5, 4] }, ]" locale="de-DE" label="last" title="Localized shares" width="220" height="30" /> </span> ``` `format`/`locale` control the share numbers — the accessible summary and endpoint labels follow the locale's own percent formatting ("66 %" in German, with a space before the sign, not "66%"). The stack itself never changes shape; only the announced and printed numbers localize. ## Edge cases [#edge-cases] ```tsx `"> <StackedArea data="[ { label: "A", values: [10] }, { label: "B", values: [5] }, ]" title="Single column" width="160" height="30" /> ``` ```tsx `" > <StackedArea data="[ { label: "A", values: [0, 0, 0, 0] }, { label: "B", values: [5, 5, 5, 5] }, ]" title="A series at zero" width="160" height="30" /> ``` A single column still stacks normally — share is well-defined from one point, it's just a vertical slice with no width to run across. A series pinned at zero collapses to a zero-height layer rather than distorting the others: the remaining series still sum to 100% of what's left. ## Why this default [#why-this-default] Values are normalized to shares before stacking, so the stack reads composition — not magnitude and composition tangled together. `order="asc"` puts the smallest series on top, where curvature distorts thickness the least. ## Accessibility [#accessibility] The accessible name is the share-shift read — **"3 series over 12 points; Mobile leads at 66% share."** The interactive entry announces every layer at once (**"Point 8 of 12: Mobile 56%, Web 36%, API 8%."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; values }[]` | ≤ 3 series (hard cap). | | `mode` | `"stacked" \| "ridge"` | Ridge = same stack, overlapping-crest skin. | | `order` | `"data" \| "asc"` | "asc" puts the smallest series on top (least distortion). | | `label` | `"last" \| "none"` | Endpoint share labels per series (deterministic drop-out). | | `labelAt` | `number` | Column whose shares feed label="last" (default: final column). The interactive entry passes the focused column so the labels track the crosshair. | | `curve` | `"linear" \| "smooth" \| "step"` | Line interpolation (default linear); ridge forces smooth. | | `colors` | `string[]` | Per-series colours, cycled; overrides --mc-cat-N. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # StarSpoke (/docs/charts/star-spoke) StarSpoke answers "what is this entity's profile across a few metrics — and which entity in a set is the odd one out?". Spokes radiate from the center and their length encodes each value. There is no connecting polygon, ever: the enclosed area of a radar chart lies about magnitude and axis order, and the research is clear that contour-free wins for spotting outliers. ```tsx <StarSpoke data="[ { label: "Speed", value: 0.9 }, { label: "Power", value: 0.6 }, { label: "Range", value: 0.5 }, { label: "Cost", value: 0.3 }, { label: "Ease", value: 0.7 }, ]" dots="tips" title="Product profile" size="110" /> ``` ## Install [#install] ```tsx import { StarSpoke } from "@microcharts/react/star-spoke"; <StarSpoke data={metrics} title="Product profile" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — entity profiles in small multiples, skill / capability comparison. * **Avoid for** — fewer than 3 metrics (PairedBars) or precise values (MiniBar). ## Variants [#variants] ```tsx `" > <StarSpoke data="[ { label: "Speed", value: 0.9 }, { label: "Power", value: 0.6 }, { label: "Range", value: 0.5 }, { label: "Cost", value: 0.3 }, { label: "Ease", value: 0.7 }, ]" compare="[0.5, 0.5, 0.5, 0.5, 0.5]" dots="tips" title="vs baseline" size="110" /> ``` `locale` doesn't change any in-chart mark — tip labels are metric names, never formatted numbers — but it does localize the extremes named in the accessible summary: ```tsx `" > <StarSpoke data="[ { label: "Speed", value: 1900 }, { label: "Power", value: 600 }, { label: "Range", value: 500 }, ]" domain="[0, 2000]" locale="de-DE" title="Localized summary" size="110" /> ``` ## Why this default [#why-this-default] Contour-free is the point: a connecting polygon is decoration that changes the read, exaggerating area for high-variance profiles and hiding the individual spoke lengths that actually matter for comparison. One shared domain governs every spoke in a glyph — mixed-domain metrics are the caller's normalization to state, so a set of small multiples stays honestly comparable. Every spoke sits at a fixed clock position (first at 12 o'clock, clockwise), so the axis order never shifts between instances — that fixed order, plus the default-on guide spokes, is what keeps a profile readable even where a metric's label doesn't seat. Tip labels seat at the rim, not the value tip, so a low-value spoke never drags its label into the hub. A label is dropped only when its estimated width exceeds the whole glyph; anything narrower is clamped into the reserved label ring instead, which keeps rim labels at distinct angles rather than dropping them. ## Edge cases [#edge-cases] ```tsx `" > <StarSpoke data="[ { label: "Reliability", value: 0.9 }, { label: "Throughput", value: 0.6 }, { label: "Cost efficiency", value: 0.5 }, ]" title="Small, long labels" size="48" /> ``` ```tsx `"> <StarSpoke data="[]" title="Empty" size="64" /> ``` ## Accessibility [#accessibility] The accessible name names the extremes — **"5 metrics; highest Speed (0.9), lowest Cost (0.3)."** The interactive entry rotates focus through the spokes with ←/→, announcing each metric and value. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label, value }[]` | 3–8 metrics on a shared domain. | | `dots` | `"tips" \| "none"` | `"tips"` draws endpoint dots to sharpen the outlier read. | | `guides` | `boolean` | Full-length guide spokes (read-back scaffold). | | `compare` | `number[]` | Muted ghost baseline spokes. | | `labels` | `boolean` | Spoke labels at the tips (default true; drop out below size 44). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # StationGlyph (/docs/charts/station-glyph) StationGlyph packs a full point observation into one character, the way a meteorologist's station model does: the center disc fills with sky cover, a wind barb gives direction and quantized speed, and up to three corner numerals carry temperature, dew point, and pressure. Five fields, one glyph, no legend — dense enough to tile a map, legible enough to read in a table cell. ```tsx <StationGlyph station="KSFO" cloud="0.75" wind="{ direction: 225, magnitude: 15 }" temp="16" dewpoint="9" pressure="1013" size="48" /> ``` ## Install [#install] ```tsx import { StationGlyph } from "@microcharts/react/station-glyph"; <StationGlyph station="KSFO" cloud={0.75} wind={{ direction: 225, magnitude: 15 }} temp={16} dewpoint={9} pressure={1013} /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a dense weather station model, or any multi-field reading that must fit one cell. * **Avoid for** — a single value (Delta) or a trend over time (Sparkline). ## Variants [#variants] ```tsx `"> <StationGlyph station="KJFK" cloud="1" wind="{ direction: 300, magnitude: 45 }" temp="4" dewpoint="2" pressure="988" size="48" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <StationGlyph station="STN" cloud="0.3" wind="{ direction: 0, magnitude: 0 }" size="44" /> ``` ```tsx `"> <StationGlyph cloud="0.4" size="44" /> ``` ```tsx `"> <StationGlyph size="44" /> ``` ```tsx `" > <StationGlyph station="EDDF" cloud="0.6" wind="{ direction: 90, magnitude: 22 }" temp="-3" dewpoint="-9" pressure="1024" format="{ maximumFractionDigits: 0 }" locale="de-DE" size="48" /> ``` `format`/`locale` flow through every corner numeral (temp, dew point, pressure) and the wind speed and numerals named in the accessible summary — one formatter, one locale, no per-field overrides. ## Why this default [#why-this-default] Each field rides its own channel, so nothing is inferred from a shared one: sky cover is disc area, wind is the barb (direction as angle, speed quantized into barbs so the per-barb quantum is honest), and the numerals are placed where a forecaster expects them. Wind speed is quantized rather than drawn to scale for the same reason WindBarb quantizes it — a barb count reads exactly, a tiny length does not. Absent fields simply don't render — no barb, no numeral, and no stop for the keyboard. The one field with no "absent" state is the disc itself: omitting `cloud` looks and reads exactly like a clear sky. ## Accessibility [#accessibility] The accessible name is the whole observation — **"KJFK, wind northwest 45; sky overcast, 4° / 2°, 988."** The interactive entry roves the *present* fields with ←/→ so a screen-reader user can step through station, wind, sky, temperature, dew point, and pressure one at a time — an omitted prop is not a stop — and Escape clears the focus back to the whole-observation reading. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `cloud` | `number` | Sky cover 0–1; fills the disc. | | `wind` | `{ direction, magnitude }` | Barb direction + speed. | | `step` | `number` | Wind-barb quantum — each full barb (default 10). | | `temp` | `number` | Upper-left numeral. | | `dewpoint` | `number` | Lower-left numeral. | | `pressure` | `number` | Upper-right numeral. | | `station` | `string` | Top-left identifier. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # StatusDot (/docs/charts/status-dot) StatusDot answers "what state is this thing in right now?". Every state pairs a distinct silhouette with a semantic color — filled circle, triangle, diamond, hollow ring, half-filled circle — so two states can never collapse into the same mark for the 1-in-12 colorblind readers a colored disc fails. ```tsx <span className="text-lg"> {"The API is "} <StatusDot status="ok" title="API" style="{ width: "0.6em", height: "0.6em" }" /> {" operational."} </span> ``` ## Install [#install] ```tsx import { StatusDot } from "@microcharts/react/status-dot"; <StatusDot status="ok" title="API" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — service lists, inline state in a sentence, monitoring rows. * **Avoid for** — quantities, trends, or vocabularies past \~6 states (marks stop being memorable). ## The state contract [#the-state-contract] | status | glyph | token | | ------- | ------------------ | --------------- | | `ok` | filled circle | `--mc-positive` | | `warn` | triangle | `--mc-cat-1` | | `error` | diamond | `--mc-negative` | | `off` | hollow ring | `--mc-neutral` | | `busy` | half-filled circle | `--mc-accent` | The pairing is a contract: `color` recolors a state but never reshapes it, and a theme must never let two states share a silhouette. ## Variants [#variants] ```tsx `" > <StatusDot status="ok" title="Live" style="{ width: 18, height: 18 }" /> ``` ```tsx `" > <StatusDot status="degraded" states="{ degraded: { glyph: "triangle", token: "--mc-cat-1", label: "degraded" } }" title="Search" style="{ width: 18, height: 18 }" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <StatusDot status="degraded" title="Unknown key" style="{ width: 18, height: 18 }" /> ``` ## Why this default [#why-this-default] Shape+color pairing beats a colored disc: the five silhouettes stay distinct in grayscale, print, and forced-colors, where color-only status dots all become the same gray circle. An unknown status key renders the `off` ring with a dev warning — never a plausible-looking wrong state. ## Accessibility [#accessibility] The accessible name is the state's label — **"Status: ok."** — composed with your `title` ("API. Status: ok."). The interactive entry announces state changes through a polite live region and stays quiet on mount. `pulse` is a CSS halo that disappears entirely under `prefers-reduced-motion`. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `status` (required) | `string` | Built-in ok \| warn \| error \| off \| busy, or a key of states. | | `pulse` | `boolean` | Live-now halo (reduced-motion-gated). | | `states` | `Record<string, { glyph; token; label }>` | Extend the vocabulary; the shape+color pairing is preserved. | | `color` | `string` | Recolors the active state; never reshapes it. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # StreakSpark (/docs/charts/streak-spark) StreakSpark answers "how long is the current run, and how does it compare to the record?". A sequence of pass/fail outcomes collapses into **runs** — each run a bar whose width is its length on one shared scale. Streak runs sit low and translucent, breaks sit thin and saturated, and the **current** run is the loud accent bar at the right. The record streak wears a small triangle tick, so "are we near our best" reads without counting. ```tsx `" > <StreakSpark data="[1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 0, 0, 1, 1, 1]" label="both" title="Deploy streak" width="300" height="48" /> ``` ## Install [#install] ```tsx import { StreakSpark } from "@microcharts/react/streak-spark"; // 1 = passing build, 0 = failing build <StreakSpark data={[1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 0, 0, 1, 1, 1]} title="Deploy streak" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — pass/fail run histories, uptime and incident-free streaks, the current run against a record. * **Avoid for** — a continuous magnitude (SparkBar) or a single completion ratio (Progress). ## Variants [#variants] `data` accepts booleans, `0`/`1`, or any numbers (they pass on `> 0`, or on `>= threshold`). A `null` is a gap: it breaks the run and starts a fresh one. Everything else is a prop. ```tsx `" > <StreakSpark data="[1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 0, 0, 1, 1, 1]" label="both" title="Current and record" width="300" height="48" /> ``` ```tsx `" > <StreakSpark data="[0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0]" positive="down" label="both" title="Incident-free streak" width="300" height="48" /> ``` ```tsx = threshold — e.g. daily uptime %, target 99.5 <StreakSpark data={[99.9, 99.8, 99.6, 98.2, 99.7, 99.9, 99.6, 97.0, 99.8, 99.9]} threshold={99.5} label="both" />`" > <StreakSpark data="[99.9, 99.8, 99.6, 98.2, 99.7, 99.9, 99.6, 97.0, 99.8, 99.9]" threshold="99.5" label="both" title="Uptime streak" width="300" height="48" /> ``` ```tsx 1)} format={{ useGrouping: true }} locale="de-DE" />`" > <StreakSpark data="Array.from({ length: 1204 }, () => 1)" format="{ useGrouping: true }" locale="de-DE" label="current" title="Localized run length" width="220" height="48" /> ``` With a `locale`, the count label and the accessible summary follow that locale's own grouping — a 1,204-build streak reads **"1.204"** in German. The outcome words come from `strings`, so the whole summary localizes together. ## Edge cases [#edge-cases] ```tsx `"> <StreakSpark data="[1]" title="One build" width="160" height="24" /> ``` A lone outcome is one current run of length 1, and it is trivially its own record — the summary reads **"Current run 1 passing, unbroken."** ```tsx `"> <StreakSpark data="[0, 0, 0, 0, 0]" title="Rough week" width="200" height="24" /> ``` When nothing passes there is no completed streak: the strip is one saturated break run, no triangle tick, and the summary reads **"Current run 5 failing; no completed streak."** ## Why this default [#why-this-default] Runs, not per-outcome ticks, because the decision is about *length* — "how long have we held" and "how does that compare to our best". Width encodes run length on one shared scale, so a wide bar is a genuinely long run and the eye compares them honestly. Height and opacity encode run *type* (streak, break, current) — never magnitude — so the ribbon never implies a size it doesn't have. The record tick and the accented current bar answer the two questions the raw list can't, at a glance. ## Accessibility [#accessibility] The accessible name states the current run, the record, and how often the streak broke — **"Current run 3 passing; record 9; broke 2 times."** The interactive entry roves runs with ← →, announcing each run's length, outcome, and whether it is the record (**"Run 3 of 5: 4 passing."**). Direction is carried by height, opacity, and color together, never color alone. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `(boolean \| number \| null)[]` | Outcomes; null is a gap that breaks the run. Numbers pass on > 0. | | `positive` | `"up" \| "down"` | Which outcome is the streak: pass (up) or fail (down). | | `threshold` | `number` | With numeric data, values ≥ threshold pass. | | `label` | `"current" \| "both" \| "none"` | Count labels: the current run, the record too, or neither. | | `title` | `string` | Accessible name; joins the auto summary. | | `summary` | `string \| false` | Override or disable the auto summary. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # TallyMarks (/docs/charts/tally-marks) TallyMarks answers "how many?" the way a human actually counts — in four-and-strike clusters of five. The count reads back exactly: no scale to calibrate, no color to decode. Past `total` the marks stop growing and a `+N` numeral tells the truth, so a cell never blows out its width. Marks are never resized to fit — width grows with the count until the cap, then the numeral takes over. ```tsx <TallyMarks value="23" title="Signatures" height="20" /> ``` ## Install [#install] ```tsx import { TallyMarks } from "@microcharts/react/tally-marks"; <TallyMarks value={23} title="Signatures" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a small running count in a sentence or cell, a live event or score counter, or an editorial hand-tallied context. * **Avoid for** — large magnitudes (MiniBar), trends over time (Sparkline), or proportions (Progress). ## Variants [#variants] ```tsx <TallyMarks value={38} total={20} />`" > <span className="inline-flex gap-4 items-center"> <TallyMarks value="17" pen="drawn" height="20" /> <TallyMarks value="38" total="20" height="20" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <TallyMarks value="0" height="20" /> ``` ```tsx `"> <TallyMarks value="-5" height="20" /> ``` ```tsx `"> <TallyMarks value="5000" total="5000" height="20" /> ``` ## Why this default [#why-this-default] The ruled pen is the default because product tables want precision first — evenly ruled strokes count back fastest. The `drawn` pen adds a seeded, deterministic jitter (same count always renders identically, on the server and after hydration) for the editorial voice, and it only perturbs how each stroke is drawn — the count is never touched. Past `total`, the default `overflow="numeral"` appends a `+N` so the true total survives even when the marks can't; `overflow="clamp"` suppresses the numeral for dense columns, and the accessible name still carries the exact count. ## Accessibility [#accessibility] The accessible name is the exact count — **"17 counted."** — always the true value, even when the marks overflow to a `+N` numeral or clamp. The interactive entry announces the new total through a polite live region on change and draws newly added marks in with a brief, reduced-motion-gated sweep. A count has no sub-parts, so focus reads the summary and there is no cursor to move. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The count. Floored; negatives clamp to 0. | | `total` | `number` | Marks drawn before overflow (default 25). | | `overflow` | `"numeral" \| "clamp"` | numeral appends +N; clamp stops drawing. The summary always keeps the true count. | | `pen` | `"ruled" \| "drawn"` | Hand-drawn jitter for editorial contexts. | 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](/docs/quickstart#the-shared-grammar). # TapeGauge (/docs/charts/tape-gauge) TapeGauge answers "what is it now, is that OK, and where is it heading?" for a single live reading — airspeed, throughput, temperature, queue depth. The scale scrolls past a fixed center pointer, so the value stays parked where your eye already is; semantic zones mark the safe, caution, and danger bands; and a stack of chevrons encodes the rate of change as a channel entirely separate from the level. It is the aviation primary-flight-display tape, shrunk to a word. ```tsx <TapeGauge value="142" rate="1" zones="[ { from: 100, to: 130, tone: "pos" }, { from: 130, to: 150, tone: "warn" }, { from: 150, to: 200, tone: "neg" }, ]" span="60" title="Airspeed" width="46" height="72" /> ``` ## Install [#install] ```tsx import { TapeGauge } from "@microcharts/react/tape-gauge"; <TapeGauge value={142} rate={1} zones={zones} span={60} title="Airspeed" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a live changing reading with a safe/caution band; value plus trend at a glance. * **Avoid for** — a history you want to scan (Sparkline) or a single static number (Delta). ## Variants [#variants] ```tsx // label="none" drops the in-chart readout for an external number <TapeGauge value={142} rate={1} zones={zones} span={60} label="none" />`" > <span className="inline-flex items-end gap-6"> <TapeGauge value="142" rate="-1" zones="[ { from: 100, to: 130, tone: "pos" }, { from: 130, to: 150, tone: "warn" }, { from: 150, to: 200, tone: "neg" }, ]" span="60" orientation="horizontal" title="Airspeed" width="160" height="30" /> <TapeGauge value="142" rate="1" zones="[ { from: 100, to: 130, tone: "pos" }, { from: 130, to: 150, tone: "warn" }, { from: 150, to: 200, tone: "neg" }, ]" span="60" label="none" title="Airspeed" width="30" height="44" /> </span> ``` ```tsx `" > <TapeGauge value="14200" format="{ maximumFractionDigits: 0 }" locale="de-DE" title="Localized reading" width="46" height="68" /> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, both the in-gauge readout and the accessible summary follow that locale's own grouping ("14.200" in German, not "14,200"). ## Edge cases [#edge-cases] ```tsx `" > <TapeGauge value="NaN" title="Sensor offline" width="46" height="68" /> ``` ```tsx `" > <TapeGauge value="142" rate="1" span="40" title="Airspeed, unzoned" width="46" height="68" /> ``` ## Why this default [#why-this-default] The value is pinned at the pointer and the scale moves instead, because on a live instrument the one thing you never want to hunt for is the current reading. Rate lives on its own channel — chevrons, not position — so a fast climb and a high value are never confused for one another, the failure mode that sinks a naïve gauge. The visible span is fixed while the value updates, so a jump reads as motion of the scale rather than a silent rescale that hides how far it moved. ## Accessibility [#accessibility] The accessible name states the level, the trend word, and the containing zone — **"Now 142, rising; in the 130–150 zone."** The interactive entry re-announces the reading through a polite live region, throttled so a rapidly changing value never floods a screen reader, and focus reads the full summary on demand. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The current level; parked at the pointer. | | `rate` | `number` | Signed units/tick; drives the chevrons. | | `zones` | `{ from, to, tone }[]` | Semantic bands on the scale. | | `span` | `number` | Visible scale extent; fixed while live. | | `rateTiers` | `[number, number]` | Thresholds for 1 and 2 chevrons (default [span/60, span/15]). | | `orientation` | `"vertical" \| "horizontal"` | Tape direction (default vertical). | | `announceEvery` | `number` | (interactive) Minimum ms between live-region announcements as the value streams (default 5000). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Thermometer (/docs/charts/thermometer) Thermometer answers "where does this value sit on a calibrated range, and how close to the goal?" A column fills a ticked tube; the ticks calibrate the read, which is what buys the precision. The fill always anchors at the bottom of the range — never re-zeroed, never log — and an optional target line crosses the tube to mark the goal. The bulb is instrument chrome (always full); it is not data, so its area means nothing. ```tsx <Thermometer value="72" target="80" title="Fundraiser" height="56" /> ``` ## Install [#install] ```tsx import { Thermometer } from "@microcharts/react/thermometer"; <Thermometer value={72} target={80} title="Fundraiser" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — a fundraising or goal-progress read, a capacity or utilization gauge in a cell, or any value against a stated range. * **Avoid for** — trends (Sparkline), proportions of a whole (SegmentedBar), or many series. ## Variants [#variants] ```tsx <Thermometer value={72} domain={[32, 100]} ticks={[32, 50, 68, 86, 100]} />`" > <span className="inline-flex gap-6 items-center"> <Thermometer value="62" orientation="horizontal" bulb="false" width="110" /> <Thermometer value="72" domain="[32, 100]" ticks="[32, 50, 68, 86, 100]" height="60" /> </span> ``` ## Edge cases [#edge-cases] ```tsx `"> <Thermometer value="130" domain="[0, 100]" title="Overrun" height="48" /> ``` ```tsx `"> <Thermometer value="0" title="Empty" height="48" /> ``` ```tsx `" > <Thermometer value="7234" domain="[0, 10000]" target="8000" format="{ maximumFractionDigits: 0 }" locale="de-DE" label="value" title="Fundraiser" height="56" /> ``` The accessible summary's value, domain, and target all go through the same locale-aware formatter, so "7,234" becomes "7.234" in German grouping. ## Why this default [#why-this-default] Vertical with the bulb is the default because the instrument metaphor is the point — a filling tube reads as "toward the goal" instantly. Horizontal exists for table cells where a vertical tube cannot fit, and `bulb={false}` drops the reservoir when the metaphor runs too warm for the context. The `domain` defaults to `[0, 100]` because a calibrated instrument needs a stated range; auto-fitting would silently move the scale under the reader. A value beyond the domain clamps the fill but the accessible name always reports the true number — the reading is never silently clipped. ## Accessibility [#accessibility] The accessible name states the value on its scale — **"62 on a 0–100 scale."** — and appends the goal when a target is set. The interactive entry reveals the exact value on hover or focus, glides the fill to its new level with a reduced-motion-gated transition, and announces each change through a polite live region. This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | The reading. | | `target` | `number` | A goal tick across the tube. | | `domain` | `[number, number]` | The calibrated range (default [0, 100]). | | `ticks` | `number \| number[]` | Tick count or explicit values. | | `orientation` | `"vertical" \| "horizontal"` | Horizontal fits table cells. | | `bulb` | `boolean` | Draw the reservoir bulb (default true). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # TimeInRange (/docs/charts/time-in-range) TimeInRange answers "how much of the period was the metric inside its acceptable corridor — and which side did it miss on?". Zones sit in a fixed semantic order — below, in, above — so the strip is read by position first and color second. The in-range percent is the one number that matters. ```tsx <TimeInRange data="{ below: 9, in: 72, above: 19 }" title="Time in range" width="240" height="22" /> ``` ## Install [#install] ```tsx import { TimeInRange } from "@microcharts/react/time-in-range"; <TimeInRange data={{ below: 9, in: 72, above: 19 }} title="Time in range" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — SLO / uptime corridors, glucose-style time-in-range, thermal or budget bands. * **Avoid for** — ranking parts (SegmentedBar) or a single ratio (Progress). ## Variants [#variants] ```tsx `" > <TimeInRange data="{ severeBelow: 2, below: 7, in: 72, above: 15, severeAbove: 4 }" orientation="vertical" label="all" title="Vertical" width="28" height="130" /> ``` ```tsx `"> <TimeInRange data="{ severeBelow: 3, below: 8, in: 64, above: 18, severeAbove: 7 }" title="Severity tiers" width="240" height="22" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <TimeInRange data="{ below: 0, in: 0, above: 0 }" title="No readings yet" width="160" height="16" /> ``` ```tsx `" > <TimeInRange data="{ below: 3, in: 90, above: 7 }" label="all" title="Mostly in range" width="60" height="10" /> ``` ## Why this default [#why-this-default] Zone order is semantic and immutable — it is never sorted by magnitude, because the position of a miss (too low vs too high) is half the reading. Severity tiers are drawn with the same hue at greater ink weight, so the strip never relies on color alone. Percent labels round with largest-remainder rounding so they always sum to 100, and the summary reads the same integers as the label. ## Accessibility [#accessibility] The accessible name leads with the headline and then the misses — **"72% in range, 7% below, 15% above, 2% severe low, 4% severe high."** The interactive entry roves the zones; each announces its share (**"in range: 72%."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `TimeInRangeDatum` | Counts or fractions; normalized to 1. | | `orientation` | `"horizontal" \| "vertical"` | Vertical suits clinical columns and KPI cards. | | `label` | `"in" \| "all" \| "none"` | The in-range headline, a full audit, or clean. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # TokenConfidence (/docs/charts/token-confidence) TokenConfidence answers "which parts of this generated text should I double-check?". The text itself is the chart: confidence becomes a typographic underline beneath each token, in three discrete tiers — confident tokens get no mark at all, so reading stays primary and only the uncertain words draw the eye. ```tsx `" > <TokenConfidence data="[ { token: "The", confidence: 0.98 }, { token: " Treaty", confidence: 0.93 }, { token: " of", confidence: 0.99 }, { token: " Westphalia", confidence: 0.71 }, { token: " was", confidence: 0.96 }, { token: " signed", confidence: 0.9 }, { token: " in", confidence: 0.97 }, { token: " 1648", confidence: 0.44 }, { token: ", ending the Thirty", confidence: 0.63 }, { token: " Years' War", confidence: 0.85 }, { token: " over", confidence: 0.31 }, { token: " a decade", confidence: 0.38 }, { token: ".", confidence: 0.99 }, ]" title="Model answer" style="{ fontSize: "1.05rem" }" /> ``` ## Install [#install] ```tsx import { TokenConfidence } from "@microcharts/react/token-confidence"; <TokenConfidence data={tokens} title="Model answer" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — LLM answers in chat or transcripts, flagging text to review. * **Avoid for** — numeric confidence auditing (use CalibrationStrip) or a single score (Delta). ## Sizing [#sizing] The text is the chart, so it inherits the surrounding font size — there is no `width`/`height`. Set `style={{ fontSize }}` or let it flow inline with your prose. ## Variants [#variants] ```tsx `" > <TokenConfidence data="[ { token: "Likely", confidence: 0.92 }, { token: " Paris", confidence: 0.62 }, { token: ", maybe", confidence: 0.3 }, { token: " Lyon", confidence: 0.28 }, ]" style="{ fontSize: "1.05rem" }" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <TokenConfidence data="[ { token: "The", confidence: 0.95 }, { token: " answer", confidence: 0.99 }, { token: " is", confidence: 0.97 }, { token: " Paris", confidence: 0.9 }, ]" style="{ fontSize: "1.05rem" }" /> ``` Every token clears the `hi` threshold, so nothing is flagged — the sentence renders as plain, unmarked text. That absence of marks is the finding: nothing here needs a second look. ```tsx `"> <TokenConfidence data="[]" style="{ fontSize: "1.05rem" }" /> ``` An empty `data` array renders nothing and reports **"No tokens."** to assistive tech. ## Why this default [#why-this-default] The tiers are discrete — confident, unsure, guessing — never a continuous gradient, because people calibrate categorically: a smooth colour ramp reads as noise, but "double-check this word" reads instantly. Confident tokens carry no mark at all, and the two flagged tiers differ in **stroke style** as well as colour — unsure is a solid underline, guessing a dotted one — so the tier never depends on colour alone. For auditing exact probabilities, reach for [CalibrationStrip](/docs/charts/calibration-strip) instead. ## Accessibility [#accessibility] The accessible name is the tier tally — **"4 tokens: 1 confident, 1 unsure, 2 guessing."** The interactive entry gives each flagged token a roving tab stop; ←/→ move between them (skipping confident tokens), announcing each one's tier and confidence. ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ token, confidence }[]` | Tokens + confidences. | | `tiers` | `readonly [number, number]` | lo/hi thresholds — the only tuning. | | `show` | `"flagged" \| "all"` | All also hairlines confident tokens. | | `legend` | `boolean` | Appends the 1-line inline key. | 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](/docs/quickstart#the-shared-grammar). # TraceFold (/docs/charts/trace-fold) TraceFold answers "where did the latency go — which spans, at which depth, on the path that actually determined the total?". Each span is a rect placed by its start time, sized by its duration, and stacked by its nesting depth. The critical path — the chain of spans that bound the total — is accented and everything else muted, so the answer to "which spans mattered" is immediate. ```tsx \`\${Math.round(n)} ms\`} title="Request trace" />`" > <TraceFold data="[ { label: "request", start: 0, duration: 214, depth: 0 }, { label: "db.query", start: 10, duration: 86, depth: 1, parent: 0 }, { label: "auth", start: 0, duration: 8, depth: 1, parent: 0 }, { label: "render", start: 96, duration: 60, depth: 1, parent: 0 }, { label: "serialize", start: 156, duration: 40, depth: 1, parent: 0 }, { label: "index-scan", start: 12, duration: 70, depth: 2, parent: 1 }, { label: "decode", start: 82, duration: 12, depth: 2, parent: 1 }, { label: "log", start: 200, duration: 14, depth: 1, parent: 0 }, { label: "gc", start: 90, duration: 5, depth: 2, parent: 1 }, ]" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" title="Request trace" width="300" height="48" /> ``` ## Install [#install] ```tsx import { TraceFold } from "@microcharts/react/trace-fold"; <TraceFold data={spans} title="Request trace" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — request traces, flame charts, p95-exemplar latency breakdowns. * **Avoid for** — a single duration (Bullet) or a time series (Sparkline). ## Variants [#variants] ```tsx \`\${Math.round(n)} ms\`} />`" > <TraceFold data="[ { label: "request", start: 0, duration: 214, depth: 0 }, { label: "db.query", start: 10, duration: 86, depth: 1, parent: 0 }, { label: "render", start: 96, duration: 60, depth: 1, parent: 0 }, { label: "index-scan", start: 12, duration: 70, depth: 2, parent: 1 }, ]" emphasis="none" format="{ style: "unit", unit: "millisecond", unitDisplay: "short", maximumFractionDigits: 0 }" title="Structure" width="300" height="44" /> ``` ```tsx `" > <TraceFold data="[ { label: "request", start: 0, duration: 14868, depth: 0 }, { label: "db.query", start: 1200, duration: 9234, depth: 1, parent: 0 }, ]" format="{ style: "unit", unit: "millisecond", unitDisplay: "narrow", maximumFractionDigits: 0 }" locale="de-DE" title="Localized durations" width="220" height="32" /> ``` `format` also takes `Intl.NumberFormatOptions` — with a `locale`, the accessible summary's numbers follow that locale's own grouping and decimal marks ("14.868 ms" in German, not "14,868 ms"). In-rect text stays the plain span label either way; only the announced numbers are localized. ## Edge cases [#edge-cases] ```tsx `"> <TraceFold data="[{ label: "request", start: 0, duration: 42, depth: 0 }]" title="Single span" width="160" height="24" /> ``` ```tsx `" > <TraceFold data="[ { label: "request", start: 0, duration: 120, depth: 0 }, { label: "db.query", start: 10, duration: 70, depth: 1, parent: 0 }, { label: "index-scan", start: 12, duration: 40, depth: 2, parent: 1 }, ]" title="Squeezed" width="200" height="24" /> ``` ## Why this default [#why-this-default] Accenting the critical path because "which spans mattered" is the question a uniform flame strip doesn't answer — the eye goes straight to the chain that set the total. Widths are durations on one linear shared time scale, never per-row normalized, so a wide span is genuinely a slow span. The only documented width distortion is a one-unit floor for zero-duration spans, and the critical-path walk is deterministic (ties resolve to the earliest start). ## Accessibility [#accessibility] The accessible name names the biggest span and its path status — **"4 spans over 214 ms; longest db.query (86 ms) on the critical path."** The interactive entry roves spans within a depth with ←/→ and between depths with ↑/↓, announcing each span's duration, share of the total, depth, and whether it is on the critical path. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `Span[]` | Flat span list; parent = index. | | `emphasis` | `"critical" \| "none"` | Mute non-critical spans, or uniform. | | `labels` | `boolean` | Width-gated in-rect labels. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # TreeRings (/docs/charts/tree-rings) TreeRings answers "how did growth accumulate, period over period?" like the rings of a tree: the oldest period is at the centre and each new period adds a ring outward, whose **thickness** is that period's value. The channel is thickness, not area — equal thickness at a larger radius spans more area (the ring illusion), so read the thicknesses, not the wedges; exact per-period reads steer to `SparkBar`. ```tsx <TreeRings data="[8, 12, 10, 18, 22, 15, 20, 14]" label="last" unit="years" periodWord="year" title="Account age" size="40" /> ``` ## Install [#install] ```tsx import { TreeRings } from "@microcharts/react/tree-rings"; <TreeRings data={years} unit="years" periodWord="year" title="Account age" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — account or company age at a glance, a cohort-age marker in a table cell, or a per-period growth story in a KPI card. * **Avoid for** — exact per-period reads (SparkBar), many periods (over twenty-four), or non-cumulative series. ## Variants [#variants] ```tsx <TreeRings data={years} total={200} />`" > <span className="inline-flex gap-6 items-center"> <TreeRings data="[8, 12, 10, 18, 22, 15, 20, 14]" rings="fill" size="44" /> <TreeRings data="[8, 12, 10, 18, 22, 15, 20, 14]" total="200" size="44" /> </span> ``` ```tsx `"> <TreeRings data="[820, 1240, 990, 1810]" label="last" locale="de-DE" title="Localized growth" size="44" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <TreeRings data="[8, 12, 0, 18, 22]" title="A flat quarter" size="44" /> ``` ```tsx `"> <TreeRings data="[]" title="New account" size="44" /> ``` ## Why this default [#why-this-default] Stroke rings are the default because at twenty-four pixels hairlines keep the disc quiet and let the accent ring — the current period, drawn 1.5× heavier in the accent color (weight and color, never color alone) — stay loud. The channel is radial **thickness**, and the docs say so explicitly, because equal thickness at a larger radius spans more area. TreeRings never enforces a minimum visual thickness: a near-zero period looks near-zero, and a zero-value period collapses its two boundaries onto each other. Pass `total` for the cohort-age story — the disc then fills only Σdata/total of the radius, so a young account reads as part-grown. ## Accessibility [#accessibility] The accessible name summarizes the growth — **"8 periods; latest 14, biggest 22 in period 5."** The interactive entry steps the rings from the centre out with ←/→ (or hover), announcing each period as "Year 5: 22." The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Per-period growth, oldest first. | | `highlight` | `"last" \| "none" \| number` | Which period's ring to pick out. | | `total` | `number` | Expected lifetime Σ — the disc fills only Σdata/total. | | `rings` | `"stroke" \| "fill"` | Boundary rings (default) or filled annuli. | | `periodWord` | `string` | Singular period noun for the summary (default "period"). | | `unit` | `string` | Plural period noun for the summary (default "periods"). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # TrendArrow (/docs/charts/trend-arrow) TrendArrow answers "which way is this moving?" at glyph size. The shape *is* the direction — up, down, or a flat bar — and color only reinforces it, so the read survives grayscale, print, and forced-colors. When the magnitude matters, reach for [Delta](/docs/charts/delta) instead. ```tsx `" > <span className="text-lg"> {"Latency "} <TrendArrow value="-0.08" positive="down" format="{ style: "percent", maximumFractionDigits: 0 }" title="Latency vs last week" style="{ width: "1em", height: "1em" }" /> {" improved again this week."} </span> ``` ## Install [#install] ```tsx import { TrendArrow } from "@microcharts/react/trend-arrow"; <TrendArrow value={-0.08} positive="down" title="Latency vs last week" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — table direction columns, dense dashboards, inline movement cues. * **Avoid for** — exact magnitudes (Delta) or series shape (Sparkline). ## Sizing [#sizing] The glyph is a fixed 16-unit box that scales like an image — size it with CSS. With `showValue` the viewBox widens to reserve a gutter for the number, so text never paints outside the chart. ## Variants [#variants] Three glyph weights for three densities, an honest noise floor, and the number when the glyph alone is too terse. ```tsx <TrendArrow value={1} glyph="triangle" /> <TrendArrow value={1} glyph="chevron" />`" > <span className="inline-flex items-center gap-3"> <TrendArrow value="1" glyph="arrow" title="Arrow" style="{ width: 20, height: 20 }" /> <TrendArrow value="1" glyph="triangle" title="Triangle" style="{ width: 20, height: 20 }" /> <TrendArrow value="1" glyph="chevron" title="Chevron" style="{ width: 20, height: 20 }" /> </span> ``` ```tsx `" > <span className="inline-flex items-center gap-3"> <TrendArrow value="0.01" flatBand="0.02" title="Within noise" style="{ width: 20, height: 20 }" /> </span> ``` ```tsx `"> <TrendArrow value="0.12" format="{ style: "percent", maximumFractionDigits: 0 }" title="Weekly change" style="{ height: 22 }" /> ``` ```tsx `"> <TrendArrow value="-0.08" positive="down" title="Latency" style="{ width: 20, height: 20 }" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <TrendArrow value="0" title="No change" style="{ height: 20 }" /> ``` ```tsx `"> <TrendArrow value="Number.NaN" title="Invalid" style="{ height: 20 }" /> ``` ```tsx `"> <TrendArrow value="12483" format="{ maximumFractionDigits: 0 }" locale="de-DE" title="Signups" style="{ height: 22 }" /> ``` `format`/`locale` reach `showValue`'s number and the accessible summary's magnitude together — "12,483" becomes "12.483" in German grouping. ## Why this default [#why-this-default] The arrow (shaft + head) stays legible at 8 px and in forced-colors where lighter marks blur; the glyph never scales with magnitude — an arrow twice as long would be a lie at this precision. `flatBand` exists so tiny wiggles don't read as movement: declare your noise floor instead of letting every ±0.1% look like a trend. ## Accessibility [#accessibility] The default accessible name is the factual direction — **"Up 12%."**, **"No change."** within the flat band, **"No data."** for non-finite input. `positive="down"` flips only the color, never the glyph or the words. The interactive entry announces direction changes through a polite live region and pulses the glyph (gated on reduced motion). This chart is a single unit, so there is nothing to rove between: a click, tap, `Enter` or `Space` selects it and fires `onSelect`, and no selection stays pinned. That is the scalar half of the shared [interaction contract](/docs/accessibility#one-interaction-contract). ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `value` (required) | `number` | Signed change; sign → direction, magnitude only via showValue/summary. | | `flatBand` | `number` | Noise floor: \|value\| ≤ flatBand renders the flat glyph. | | `glyph` | `"arrow" \| "triangle" \| "chevron"` | Mark weight: default legibility, dense cells, inline text. | | `showValue` | `boolean` | Append the formatted value in a right gutter. | | `positive` | `"up" \| "down"` | Which direction is good (colors only, never the glyph). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # VolumeProfile (/docs/charts/volume-profile) VolumeProfile answers "at which *level* did activity concentrate — not when?". It is a histogram turned perpendicular to the usual trend axis: the level runs vertically and bars extend horizontally by the mass of activity at each level. The modal level — the point of control, or POC — is accented, and the value area (the levels holding most of the activity) is shaded. ```tsx `" > <VolumeProfile data="[ { level: 134, weight: 3 }, { level: 136, weight: 6 }, { level: 138, weight: 11 }, { level: 140, weight: 18 }, { level: 142, weight: 26 }, { level: 144, weight: 20 }, { level: 146, weight: 12 }, { level: 148, weight: 7 }, { level: 150, weight: 4 }, ]" title="Volume by price" width="120" height="90" /> ``` ## Install [#install] ```tsx import { VolumeProfile } from "@microcharts/react/volume-profile"; <VolumeProfile data={profile} title="Volume by price" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — volume-at-price, level-of-activity distributions, load by tier. * **Avoid for** — a time series (Sparkline) or when the timing is what matters. ## Variants [#variants] ```tsx `" > <VolumeProfile data="[ { level: 138, weight: 11 }, { level: 140, weight: 18 }, { level: 142, weight: 26 }, { level: 144, weight: 20 }, { level: 146, weight: 12 }, ]" align="right" title="Right side" width="120" height="70" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <VolumeProfile data="[142, 142, 142, 142]" title="Single level" width="80" height="40" /> ``` ```tsx `" > <VolumeProfile data="[]" title="Empty" width="80" height="40" /> ``` ## Why this default [#why-this-default] A perpendicular histogram because "where" is a different question from "when", and no time-axis chart can answer it. The value area is a stated convention — `valueArea` defaults to `0.7`, and the fraction is stated in the summary — not an implied confidence interval. The modal bin is the only accented mark, because "where did activity pile up" is the one question the shape is built to answer. ## Accessibility [#accessibility] The accessible name states where activity concentrates — **"Activity concentrates at 142.33 (POC); 70% within 140.33–145.67."** (the right-aligned demo's 5-level profile, default 12 bins). An even distribution reads **"Activity is evenly spread."** The interactive entry roves the levels with ↑/↓, announcing each level's share of activity and flagging the POC. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ level, weight }[] \| number[]` | Activity mass per level, or raw levels. | | `valueArea` | `number` | Mass fraction of the shaded value area (0.7). | | `align` | `"left" \| "right"` | Which way bars grow. | | `label` | `"poc" \| "none"` | The POC level beside the accent bar. | | `bins` | `number` | Number of histogram bins (default 12). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Waterfall (/docs/charts/waterfall) Waterfall answers "how did the deltas compose into the total?" — the P\&L bridge, in a cell. Sign is encoded by vertical direction from the running level AND by valence color, never color alone. ```tsx <Waterfall data="[ { label: "Product", value: 42 }, { label: "Services", value: 18 }, { label: "Refunds", value: -12 }, { label: "Opex", value: -26 }, { label: "FX", value: 5 }, ]" open="60" title="Net income bridge" width="220" height="30" /> ``` ## Install [#install] ```tsx import { Waterfall } from "@microcharts/react/waterfall"; <Waterfall data={steps} open={60} title="Net income bridge" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — P\&L bridges in table cells, net-change decomposition in KPI cards. * **Avoid for** — unordered category comparison (MiniBar), or more than \~8 steps. ## Variants [#variants] ```tsx <Waterfall data={steps} open={60} totalBar={false} />`" > <span className="inline-flex flex-col gap-3"> <Waterfall data="[ { label: "Product", value: 42 }, { label: "Services", value: 18 }, { label: "Refunds", value: -12 }, { label: "Opex", value: -26 }, { label: "FX", value: 5 }, ]" open="60" title="Net income bridge" width="240" height="30" /> <Waterfall data="[ { label: "Product", value: 42 }, { label: "Services", value: 18 }, { label: "Refunds", value: -12 }, { label: "Opex", value: -26 }, { label: "FX", value: 5 }, ]" open="60" totalBar="false" title="Steps only" width="220" height="30" /> </span> ``` ```tsx `" > <Waterfall data="[ { label: "Cloud", value: -8 }, { label: "Headcount", value: 14 }, { label: "Vendors", value: -5 }, { label: "Travel", value: -3 }, ]" open="40" positive="down" title="Cost bridge" width="220" height="30" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <Waterfall data="[ { label: "Q1", value: -20 }, { label: "Q2", value: -35 }, { label: "Q3", value: -10 }, ]" open="0" title="All losses" width="180" height="30" /> ``` ```tsx `" > <Waterfall data="[ { label: "Product", value: 30 }, { label: "Flat", value: 0 }, { label: "Refunds", value: -12 }, ]" open="50" title="Zero step" width="180" height="30" /> ``` ## Why this default [#why-this-default] The zero-anchored total bar stays on by default: a waterfall without a grounded total is unverifiable — floating bars alone can't be checked against reality. Hairline connectors carry the running level between steps without adding ink. ## Accessibility [#accessibility] The accessible name states the endpoints and the split — **"From 60 to 87 over 5 steps: +65 gains, −38 losses."** The interactive entry steps through the bridge (**"Refunds: −12, running 108."**). The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `{ label; value }[]` | Signed deltas in order. | | `open` | `number` | Opening level (prior-period close). | | `totalBar` | `boolean` | Zero-anchored closing total bar (default on). | | `positive` | `"up" \| "down"` | "down" = decreases are good (cost breakdowns). | | `label` | `"none" \| "delta"` | "delta" (default) prints each step's signed value in a band below the plot; the biggest movers win when labels would collide. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # Waveform (/docs/charts/waveform) Waveform answers "what is the shape of a high-frequency signal — where are its spikes and silences — at word width?". It compresses with max-per-bucket, never a mean, so a single spike survives the squeeze to a sparkline width. The peak is disclosed in the accessible summary. ```tsx (i === 126 ? 0.82 : Math.sin(i / 3) * 0.15 + Math.sin(i / 11) * 0.35) * (1 - Math.abs(i - 100) / 260), )} title="Voice memo" />`" > <Waveform data="Array.from({ length: 200 }, (_, i) => (i === 126 ? 0.82 : Math.sin(i / 3) * 0.15 + Math.sin(i / 11) * 0.35) * (1 - Math.abs(i - 100) / 260))" progress="0.63" title="Voice memo" width="300" height="30" /> ``` ## Install [#install] ```tsx import { Waveform } from "@microcharts/react/waveform"; <Waveform data={samples} title="Voice memo" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — voice-memo / audio scrubbers, high-frequency log or request volume. * **Avoid for** — exact values (Sparkline) or categorical state (Hypnogram). ## Variants [#variants] ```tsx Math.sin(i / 3) * 0.4 * (1 - Math.abs(i - 100) / 220))} mode="envelope" />`" > <Waveform data="Array.from({ length: 200 }, (_, i) => Math.sin(i / 3) * 0.4 * (1 - Math.abs(i - 100) / 220))" mode="envelope" title="Envelope" width="280" height="30" /> ``` ```tsx `"> <Waveform data="[0.2, 0.5, 0.82, 0.4, 0.1]" locale="de-DE" title="Localized peak" width="90" height="22" /> ``` With a `locale`, the announced peak follows that locale's own decimal mark — "0,82" in German, not "0.82". ## Edge cases [#edge-cases] ```tsx `"> <Waveform data="[0.6]" title="One sample" width="60" height="20" /> ``` ```tsx `"> <Waveform data="[0, 0, 0, 0, 0, 0, 0, 0]" title="Silent" width="100" height="20" /> ``` A single sample renders as one bucket, top-to-bottom. All-zero data renders every bucket at the shared 0.4-unit "silent" tick height, and the accessible summary says **"Silent."** rather than reporting a zero peak. A `null` in the data behaves the same as a true zero for any bucket where it's the only sample — `maxPerBucket` skips non-finite values when picking the bucket's peak, and a bucket with nothing finite in it falls back to that same silence tick, so a genuine gap and real silence render identically here (unlike Sparkline's line break). ## Why this default [#why-this-default] Bars with max-per-bucket are the only compression that can't hide an incident — averaging a bucket would erase the very spike someone is looking for. The auto domain is symmetric ±max|data|, which reads shape honestly and discloses the peak in the summary; for absolute loudness comparison across rows, pass an explicit shared `domain` so quiet data is never silently rescaled to look loud. ## Accessibility [#accessibility] The accessible name discloses the peak — **"Peak 0.398 at 50% through 200 samples."** Pure silence reads **"Silent."** rather than blank. The interactive entry roves the buckets, announcing each bucket's position and peak amplitude. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | Amplitude samples; negatives allowed. | | `progress` | `number` | 0–1 played fraction; left buckets tint accent. | | `mode` | `"bars" \| "envelope"` | Envelope draws the min/max area. | | `mirror` | `boolean` | Mirror around center; false for magnitude-only. | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # WinProbWorm (/docs/charts/win-prob-worm) WinProbWorm answers "who's winning, and when did the lead flip?". It plots one win-probability series on a **fixed 0–100 axis that is never truncated** — the honesty rule for a probability — and splits the worm at the 50% line: while your side leads the line reads accent, when it trails it reads neutral, and a dot marks each lead change. Because a win-probability curve is a modelled read, the summary always says so, "per the supplied model". ```tsx <WinProbWorm data="[50, 48, 45, 52, 60, 58, 42, 38, 55, 68, 82, 90, 88, 94, 98]" sides="["home", "away"]" title="Win probability" width="220" height="28" /> ``` ## Install [#install] ```tsx import { WinProbWorm } from "@microcharts/react/win-prob-worm"; <WinProbWorm data={[50, 48, 45, 52, 60, 58, 42, 38, 55, 68, 82, 90, 88, 94, 98]} sides={["home", "away"]} title="Win probability" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## When to use it [#when-to-use-it] * **Good for** — live win or election probability where the lead flips, a modelled forecast whose crossings are the story, and any 0–100 probability you must not truncate. * **Avoid for** — a raw score or margin (Sparkline), or a value that isn't a bounded 0–100 probability. ## Variants [#variants] ```tsx <WinProbWorm data={[50, 53, 49, 52, 48, 51, 47, 50, 46, 49, 45, 48, 52]} sides={["home", "away"]} />`" > <span className="inline-flex gap-4 items-center"> <WinProbWorm data="[50, 58, 66, 74, 80, 86, 90, 93, 96, 98, 99]" sides="["home", "away"]" width="160" height="24" /> <WinProbWorm data="[50, 53, 49, 52, 48, 51, 47, 50, 46, 49, 45, 48, 52]" sides="["home", "away"]" width="160" height="24" /> </span> ``` At a taller size the biggest single momentum swing gets a hair connector and a signed delta; drop it with `markSwing={false}`, and drop the endpoint probability with `label="none"`. ```tsx `" > <WinProbWorm data="[50, 48, 45, 52, 60, 58, 42, 38, 55, 68, 82, 90, 88, 94, 98]" sides="["home", "away"]" markSwing="false" label="none" width="220" height="28" /> ``` ## Edge cases [#edge-cases] ```tsx `" > <WinProbWorm data="[50, 55.5, 61.2, 58.4, 63.5]" sides="["Ja", "Nein"]" format="{ minimumFractionDigits: 1 }" locale="de-DE" title="Modelled probability" width="180" height="26" /> ``` ```tsx `" > <WinProbWorm data="[50, 50, 50, 50, 50]" sides="["home", "away"]" title="Tied" width="160" height="24" /> ``` ```tsx `"> <WinProbWorm data="[72]" sides="["home", "away"]" title="One reading" width="110" height="24" /> ``` With a `format` and `locale`, the endpoint label and the summary format their numbers in that locale's own decimal mark — `[50, 55.5, 61.2, 58.4, 63.5]` in `de-DE` ends at **"63,5%"**. Values outside 0–100 are clamped to the axis and dev-warn — a probability cannot exceed 100. A constant series has no crossing and no swing: an all-50 series reads "even… throughout", any other constant reads "…holds X% throughout". A `null` breaks the worm into disconnected runs the way a gap should; a single point has no line to draw, so it renders just the endpoint dot and its label; `data={[]}` renders the frame with the "no data" summary. ## Why this default [#why-this-default] The fixed 0–100 axis is the whole point: a win probability that truncated its own scale would exaggerate a lead, so the axis never moves and a 2-point edge always looks like a 2-point edge. The 50% split does the reasoning for the reader — accent while your side leads, neutral while it trails, a dot at each flip — so "who's ahead, and did it ever change?" is answered before the second glance. The endpoint carries the current number, and the biggest momentum swing is marked only when there's room for it. The worm is a modelled read, never a fact, so its accessible name is framed "per the supplied model" and the chart never editorializes the forecast. ## Accessibility [#accessibility] The accessible name states the current leader, their probability, the number of lead changes, and the biggest momentum swing — **"Per the supplied model, home leads at 98%; 3 lead changes, biggest swing +17 at point 8."** — or, for a constant series, "Per the supplied model, even at 50% throughout." The interactive entry roves the points with ←/→ (Home/End jump to the ends), each announcing the leader and probability at that point, with a live readout chip. The interactive entry follows the shared [interaction contract](/docs/accessibility#one-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 [#props] | Prop | Type | Description | | --- | --- | --- | | `data` (required) | `number[]` | A single win-probability series, clamped to 0–100. | | `sides` | `[string, string]` | Names for the two sides — [>50, <50]. Default ["A", "B"]. | | `label` | `"last" \| "none"` | Print the current leader's probability at the endpoint (default "last"). | | `markSwing` | `boolean` | Mark the biggest momentum swing (default true; seat-gated). | | `animate` | `boolean` | (interactive) Opt-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](/docs/quickstart#the-shared-grammar). # WindBarb (/docs/charts/wind-barb) WindBarb answers "which way is it flowing and roughly how hard — in one character?". The shaft points along the bearing and the barbs count the magnitude: a half barb, a full barb, and a pennant are fixed quanta, so the glyph reads at a glance without a scale. Quantization is the honesty here, not a limitation — the per-barb quantum is stated next to every example. ```tsx <WindBarb direction="225" magnitude="32" step="10" label="value" title="Wind" size="64" /> ``` ## Install [#install] ```tsx import { WindBarb } from "@microcharts/react/wind-barb"; <WindBarb direction={225} magnitude={32} step={10} title="Wind" /> ``` Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent. ## Reading the barb [#reading-the-barb] WindBarb has no interactive mode — a single glyph carries the whole reading, so its accessible name is the full sentence. This gallery is the read-back key: each full barb is one `step`, a half barb is half a `step`, and a pennant is five. ```tsx `"> <span style="{ display: "inline-flex", gap: "0.5rem", flexWrap: "wrap", justifyContent: "center" }"> <WindBarb direction="0" magnitude="35" title="0°" size="40" summary="false" /> <WindBarb direction="45" magnitude="35" title="45°" size="40" summary="false" /> <WindBarb direction="90" magnitude="35" title="90°" size="40" summary="false" /> <WindBarb direction="135" magnitude="35" title="135°" size="40" summary="false" /> <WindBarb direction="180" magnitude="35" title="180°" size="40" summary="false" /> <WindBarb direction="225" magnitude="35" title="225°" size="40" summary="false" /> <WindBarb direction="270" magnitude="35" title="270°" size="40" summary="false" /> <WindBarb direction="315" magnitude="35" title="315°" size="40" summary="false" /> </span> ``` ```tsx `"> <span style="{ display: "inline-flex", gap: "0.75rem", flexWrap: "wrap", justifyContent: "center", alignItems: "center", }" > <WindBarb direction="90" magnitude="5" label="value" title="5" size="44" summary="false" /> <WindBarb direction="90" magnitude="15" label="value" title="15" size="44" summary="false" /> <WindBarb direction="90" magnitude="32" label="value" title="32" size="44" summary="false" /> <WindBarb direction="90" magnitude="55" label="value" title="55" size="44" summary="false" /> <WindBarb direction="90" magnitude="80" label="value" title="80" size="44" summary="false" /> </span> ``` ## When to use it [#when-to-use-it] * **Good for** — wind or current direction + strength, traffic flow, net migration, request routing. * **Avoid for** — exact magnitude (add `label`) or a time series (Sparkline). ## Variants [#variants] ```tsx `"> <WindBarb direction="0" magnitude="1" title="Calm" size="44" /> ``` ```tsx `"> <WindBarb direction="45" magnitude="25" mode="arrow" title="Arrow" size="44" /> ``` ```tsx `"> <WindBarb direction="225" magnitude="32" step="10" label="value" title="Wind" size="44" /> ``` ## Edge cases [#edge-cases] ```tsx `"> <WindBarb direction="0" magnitude="0" title="Calm" size="40" /> ``` ```tsx `"> <WindBarb direction="90" magnitude="-25" title="Flipped" size="40" /> ``` ```tsx `"> <WindBarb direction="225" magnitude="5000" step="10" label="value" title="Extreme" size="40" /> ``` ```tsx `"> <WindBarb direction="225" magnitude="32" step="10" label="value" format="{ maximumFractionDigits: 0 }" locale="de-DE" title="Wind" size="44" /> ``` `format`/`locale` reach the `label="value"` numeral and the accessible summary's magnitude together — the component builds one formatter and reuses it for both. ## Why this default [#why-this-default] Quantized barbs read faster and more honestly than a scaled arrow whose length you'd have to measure against a legend — the glyph is calibrated to its `step`, so counting barbs gives the magnitude directly. A near-zero magnitude renders the conventional open circle for calm rather than a zero-length shaft, and a negative magnitude flips the bearing 180° with a dev warning. ## Accessibility [#accessibility] The accessible name is the full reading — **"Southwest (225°), magnitude 32."** Calm renders as **"Calm."** Because the glyph is self-describing, rows of barbs get their interaction from the host table or list, not from the mark. ## Props [#props] | Prop | Type | Description | | --- | --- | --- | | `direction` (required) | `number` | Degrees; 0 = up/north, clockwise. | | `magnitude` (required) | `number` | Any unit; quantized into barbs. | | `step` | `number` | Full-barb quantum (each barb = step). | | `label` | `"value" \| "none"` | Numeric magnitude beside the glyph. | | `mode` | `"barb" \| "arrow"` | "arrow" swaps quantized barbs for a plain direction arrow + label. | 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](/docs/quickstart#the-shared-grammar).