Search for a command to run...
A number that rolls between values when it updates. Wraps `@number-flow/react` with locale + format awareness (decimal, compact, currency, percent). Reach for it on dashboard counters, metric tiles, score displays — anywhere a numeric value changes and the change should read.
Each character animates independently between digit values, so a jump from 1234 to 1284 rolls only the affected positions. The wrapper applies tabular-nums so digits stay column-aligned during the roll.
AnimatedNumber| Prop | Type | Default | Description |
|---|---|---|---|
value | number | — | The current numeric value. Updating triggers the roll animation. |
format | "default" | "compact" | "currency" | "percent" | "default" | Output format. compact → "1.2K", "3.4M". currency → "$1,234.00". percent → "12.4%" (pass 0.124 as the value). |
locale | string | "en-US" | BCP 47 locale tag passed to Intl.NumberFormat. |
currency | string | "USD" | ISO 4217 currency code. Only applied when format="currency". |
formatOptions | Intl.NumberFormatOptions | — | Escape hatch — merges into the resolved options. Use for non-standard formats (e.g. { signDisplay: "always" }, { minimumFractionDigits: 2 }). |
animateFromZero | boolean | false | When true, the component mounts at 0 and rolls up to value on first paint. Use for "stats land in" moments on dashboard hero counters. |
className | string | — | Forwarded to the rendered <span>. Default classes include tabular-nums for digit alignment. |
Use for values that genuinely change — dashboard counters, score tiles, live metrics. The roll is what calls attention to the change.
Pair with format="compact" for large numbers in tight spaces (sidebar nav badges, card
headers). 1.2K is more scannable than 1,247 at small sizes.
Use animateFromZero on hero metrics that load with the page. The mount roll says "we just
pulled fresh data" without needing a refresh indicator.
Wrap static numbers in AnimatedNumber. If the value never changes, a plain <span> (with
tabular-nums if needed) carries less weight.
Use animateFromZero on every counter on a page. Multiple animated numbers mounting at once
read as visual noise — reserve it for the primary metric.