Progress
Progress shows an elapsed fraction with the percent label as the datum, and keeps the true figure past 100%.
- encodes
- zero-anchored bar length + direct % label
- precision
- high
- nodes
- ≤ 4 continuous · ≤ 3 + segments
68% complete, or 3 of 5 steps: the label is the datum, which is why it is on by default. The bar gives the instant read, and the track never shrinks to make room for the label — the viewBox widens instead — so fractions stay comparable down a table column.
Install
import { Progress } from "@microcharts/react/progress";<Progress value={0.68} title="Onboarding" />Try it
When to use it
Use it for KPI cards, table completion columns, and step counts (segments). For icon-size slots use ProgressRing; for
composition use SegmentedBar.
Sizing
Variants
With label="percent" (the default) the accessible name follows format/locale too — "68 %" under de-DE rather
than the English "68%".
Edge cases
Past 100% the bar clamps at full and the label carries the true figure ("112%"). That is the one documented case where
the bar and the number disagree, and the number wins. 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 ratio it can't compute. A value of 0 renders a real, empty-but-present bar rather than
the no-data state, so "not started" and "unmeasurable" stay visually distinct.
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 for a ceiling.
Four homes
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.
Hover or focus also reveals the reading itself in a floating chip, for the sizes and label modes where the mark
does not print it; readout={false} drops the chip and keeps everything else.
Props
| Prop | Type | Notes |
|---|---|---|
| value* | 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 | interactiveOpt-in entrance motion when the chart mounts client-side — add import "@microcharts/react/motion" once. Inert on the server, on hydrated server HTML, and under prefers-reduced-motion. |
Plus the shared grammar — data, domain, color, title, summary, format — and the layout props (width, height, className, style) that every chart accepts. Interactive entries also share animate and live, and — wherever a chart has more than one navigable unit — onActive, onSelect, selectedIndex and defaultSelectedIndex; and — wherever the chart shows a hover value — readout. See the shared grammar.