Loading…

Number Flow

beta

A number whose digits roll to each new value, fading at the window's edges and spinning through rapid updates while its width follows the digits — counters, prices, percentages and compact figures, formatted by Intl.NumberFormat.

Display
1 file
1 npm package
Accessibility notes

Playground

Installation

One command and the file is in your project, or copy it in by hand.

$pnpm dlx @dowel-ui/cli add number-flow

npm packages installed: class-variance-authority.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { NumberFlow } from "@/components/ui/number-flow";

Examples

Every example the tests run, live and operable, side by side.

Default
Gallery
Formats
Growing Digits
Countdown
Rapid Updates
Prefix And Suffix
Padding And Grouping

API

Generated from the component's own types, so a prop cannot appear here without existing.

<NumberFlow>

Prop	Type	Default
`value` (required) The number to show. Update it as often as you like; each change rolls from what is on screen.	`number`	—
`as` The element rendered as the root.	`NumberFlowElement`	`"span"`
`duration` How long a roll takes, in milliseconds, scaled by the motion scale. Defaults to the slow duration token. Lower it for a value that updates continuously, so the reels stay close to the number.	`number`	—
`format` Intl.NumberFormat options: `style: "currency" \| "percent"`, `notation: "compact"`, `signDisplay`, `minimumFractionDigits`, `minimumIntegerDigits` (zero-padding), `useGrouping`, …	`Intl.NumberFormatOptions`	—
`locales` Passed to Intl.NumberFormat. Defaults to the user's locale.	`Intl.LocalesArgument`	—
`prefix` Rendered before the number, outside the reels — a unit, a label, an icon. Never animates.	`ReactNode`	—
`stagger` Milliseconds between one digit starting to roll and the next, from the leading digit. Price Flow uses 50.	`number`	`0`
`suffix` Rendered after the number, outside the reels. Never animates, but glides as the width changes.	`ReactNode`	—
`trend` Which way the reels roll. `auto` (default) rolls up on a rise, down on a fall.	`NumberFlowTrend`	`"auto"`
`variant`	`"plain" \| "tiles"`	`"plain"`

Plus every attribute of <span> except children, prefix.

<PriceFlow>

Prop	Type	Default
`value` (required) The number to show. Update it as often as you like; each change rolls from what is on screen.	`number`	—
`as` The element rendered as the root.	`NumberFlowElement`	—
`duration` How long a roll takes, in milliseconds, scaled by the motion scale. Defaults to the slow duration token. Lower it for a value that updates continuously, so the reels stay close to the number.	`number`	—
`format` Intl.NumberFormat options: `style: "currency" \| "percent"`, `notation: "compact"`, `signDisplay`, `minimumFractionDigits`, `minimumIntegerDigits` (zero-padding), `useGrouping`, …	`Intl.NumberFormatOptions`	—
`locales` Passed to Intl.NumberFormat. Defaults to the user's locale.	`Intl.LocalesArgument`	—
`prefix` Rendered before the number, outside the reels — a unit, a label, an icon. Never animates.	`ReactNode`	—
`stagger` Milliseconds between one digit starting to roll and the next, from the leading digit. Price Flow uses 50.	`number`	`50`
`suffix` Rendered after the number, outside the reels. Never animates, but glides as the width changes.	`ReactNode`	—
`trend` Which way the reels roll. `auto` (default) rolls up on a rise, down on a fall.	`NumberFlowTrend`	—
`variant`	`"plain" \| "tiles"`	`"plain"`

Plus every attribute of <span> except children, prefix.

Accessibility

The formatted value is rendered once as screen-reader text; the rolling reels are aria-hidden, so a reader hears "$1,234.56" rather than thirty digits per place. Nothing is announced when the value changes unless the consumer passes aria-live, and then only the settled value is announced (aria-atomic is set with it), never each digit. `prefix` and `suffix` are ordinary text either side of it and are read with the number; an icon passed there should be aria-hidden or labelled. A place that is fading out exists only in the hidden display. Under reduced motion every change snaps.

Quality

Measured from the source and its tests at build time.

All scores

8/8

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — does not apply
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — does not apply
No fixed widths — passes

Used in

Whole screens assembled from this component. Installing one brings this and everything else it needs with it.

Prop

Type

Default

value

The number to show. Update it as often as you like; each change rolls from what is on screen.

number

—

as

The element rendered as the root.

NumberFlowElement

"span"

duration

How long a roll takes, in milliseconds, scaled by the motion scale. Defaults to the slow duration token. Lower it for a value that updates continuously, so the reels stay close to the number.

number

—

format

Intl.NumberFormat options: style: "currency" | "percent", notation: "compact", signDisplay, minimumFractionDigits, minimumIntegerDigits (zero-padding), useGrouping, …

Intl.NumberFormatOptions

—

locales

Passed to Intl.NumberFormat. Defaults to the user's locale.

Intl.LocalesArgument

—

prefix

Rendered before the number, outside the reels — a unit, a label, an icon. Never animates.

ReactNode

—

stagger

Milliseconds between one digit starting to roll and the next, from the leading digit. Price Flow uses 50.

number

0

suffix

Rendered after the number, outside the reels. Never animates, but glides as the width changes.

ReactNode

—

trend

Which way the reels roll. auto (default) rolls up on a rise, down on a fall.

NumberFlowTrend

"auto"

variant

"plain" | "tiles"

"plain"

Prop

Type

Default

value

The number to show. Update it as often as you like; each change rolls from what is on screen.

number

—

as

The element rendered as the root.

NumberFlowElement

—

duration

How long a roll takes, in milliseconds, scaled by the motion scale. Defaults to the slow duration token. Lower it for a value that updates continuously, so the reels stay close to the number.

number

—

format

Intl.NumberFormat options: style: "currency" | "percent", notation: "compact", signDisplay, minimumFractionDigits, minimumIntegerDigits (zero-padding), useGrouping, …

Intl.NumberFormatOptions

—

locales

Passed to Intl.NumberFormat. Defaults to the user's locale.

Intl.LocalesArgument

—

prefix

Rendered before the number, outside the reels — a unit, a label, an icon. Never animates.

ReactNode

—

stagger

Milliseconds between one digit starting to roll and the next, from the leading digit. Price Flow uses 50.

number

50

suffix

Rendered after the number, outside the reels. Never animates, but glides as the width changes.

ReactNode

—

trend

Which way the reels roll. auto (default) rolls up on a rise, down on a fall.

NumberFlowTrend

—

variant

"plain" | "tiles"

"plain"