AnimatedNumber
A number that tweens smoothly to its target value — a count-up roll for live dashboard KPIs like attendee scans, throughput, or revenue. On first reveal it counts from 0; on every update it rolls from the prior value to the new one.
Import
import { AnimatedNumber } from "@roger-emerson/ploxum-primitives";Usage
<AnimatedNumber value={12480} />
// custom formatter — currency, percent, units
<AnimatedNumber
format={(n) => n.toLocaleString(undefined, { style: "currency", currency: "USD", maximumFractionDigits: 0 })}
value={184500}
/>
// live KPI — pass a new value and it rolls from the last one
<AnimatedNumber value={liveCount} />Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | number | — | Target value to count toward. Required. |
from | number | prev value, else 0 | Starting value for the tween. Defaults to the previous value, or 0 on first mount. |
format | (n: number) => string | (n) => Math.round(n).toLocaleString() | Maps the tweened value to display text. |
duration | number | 0.6 | Tween length in seconds. |
className | string | — | Merged onto the rendered span. |
ref | Ref<HTMLSpanElement> | — | Ref to the <span>. |
The span carries aria-label set to the formatted target value, so assistive tech announces the destination, not the intermediate roll.
Design rules
- KPI display only — never use it for alert, status, or validation values. Per the motion hard-rules, critical metric updates never animate; render those instantly with a plain
<span>. - Respects
prefers-reduced-motion— when reduced, the value snaps to its target with no tween. - Uses tabular numerals so digits don't reflow width as they roll.
- The roll uses
easings.outQuart(decelerating) — it settles into the value rather than overshooting, keeping data legible.