Number Flow
An animated number that smoothly transitions between values, ideal for live power and energy readings.
NumberFlow animates a number whenever its value changes, spinning each digit
from the old reading to the new one. It's a thin, locale-aware wrapper around
@number-flow/react that defaults its
locales to the document language, so formatted numbers match the active UI
locale automatically. It powers the live totals in PowerNetwork, the energy
charts, and the Sankey diagram.
Live grid power
Usage
import NumberFlow from '@epilot/spark-ui/number-flow'// Whenever `watts` changes, NumberFlow animates between the two values.
<NumberFlow value={watts} suffix="W" />Pass suffix (or prefix) as the bare unit: NumberFlow inserts the
no-break separator (NARROW_NBSP, U+202F) between the value and the unit for
you, so suffix="W" renders 1,234 W. Already-spaced strings are left as-is, so
existing call sites keep working.
NumberFlow renders an inline element and inherits font size, weight, color,
and letter-spacing from its surroundings, so style it with plain classes like
any other text. Pair it with tabular-nums so the width stays steady while digits
spin.
Examples
Text sizes
The same animated value works at any scale because it inherits font-size.
Font weights
Weight, tracking, and color are all just classes. Nothing special is needed for the animation.
Formatting
Pass a Format
(Intl.NumberFormatOptions) to render units, percentages, or currency. The
animation respects the formatted output, including grouping separators.
Locales
NumberFlow is locale-aware: the locales prop (a BCP-47 tag) drives the
grouping and decimal separators. German groups with . and uses , for
decimals; US English is the reverse. Leave locales unset to inherit the
document's lang.
Live dashboard
Several values animating together from one telemetry snapshot to the next, mixing sizes and weights.
API Reference
NumberFlow forwards every prop to @number-flow/react.
The most useful ones:
| Prop | Type | Description |
|---|---|---|
value | number | The number to display. Animates whenever it changes. Required. |
format | Format | Intl.NumberFormatOptions: units, percent, currency, fraction digits. |
prefix | string | Bare text before the number; a no-break separator is inserted after it. |
suffix | string | Bare unit after the number, e.g. "W"; a no-break separator is inserted before it. |
locales | Intl.LocalesArgument | BCP-47 tag driving grouping/decimal separators. Defaults to the document lang. |
trend | number | ((o, n) => n) | Direction digits spin. 0 disables the directional spin. |
className | string | Styles the number. Size, weight, color all inherit. |
Animations automatically respect the user's prefers-reduced-motion setting.