# Number Flow

A numeric slot machine built on Intl.NumberFormat, with custom motion support.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<DocsBaseSwitcher base="web" component="number-flow" />

<ComponentPreview name="number-flow" title="number-flow.tsx" previewClassName="h-auto py-8">
<NumberFlowDemo />
</ComponentPreview>

Number Flow animates between numeric values with a vertical slot machine. Each digit slides into place when the value changes.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add number-flow
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
No external dependencies required.
</Step>

<Step>
Copy the source into your project.
</Step>

<ComponentSource name="number-flow" title="components/ui/number-flow.tsx" />

<Step>
Update the import paths.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx title="number-flow.tsx"
import { NumberFlow } from "@/components/ui/number-flow";
```

```tsx title="number-flow.tsx"
<NumberFlow value={1234} />
```

## Formatting [#formatting]

`value` goes through `Intl.NumberFormat` for locale-aware grouping, decimals, and percent. Pass `format`, `locales`, `prefix`, `suffix` to control the output.

<ComponentPreview name="number-flow-format" title="number-flow-format.tsx" src="examples/number-flow-format.tsx">
<NumberFlowFormat />
</ComponentPreview>

```tsx
<NumberFlow value={12.5} format={{ style: "percent" }} />
<NumberFlow value={1234} prefix="$" />
<NumberFlow value={1234} suffix=" km" />
<NumberFlow value={1234} locales="de-DE" />
```

## Motion [#motion]

By default, each digit slides with a 900ms "cubic-bezier(0.2, 0, 0.2, 1)" transition. Pass "motion" to override duration and easing.

<ComponentPreview name="number-flow-motion" title="number-flow-motion.tsx" src="examples/number-flow-motion.tsx">
<NumberFlowMotion />
</ComponentPreview>

| Value | Result |
| :-- | :-- |
| omitted | 900ms "cubic-bezier(0.2, 0, 0.2, 1)" |
| "150" | 150ms default easing |
| "150ms" | 150ms default easing |
| "1s" | 1000ms default easing |
| "200 ease-out" | 200ms custom easing |
| "600 cubic-bezier(0.16, 1, 0.3, 1)" | 600ms custom cubic-bezier |
| "off" | No transition |

```tsx
<NumberFlow motion="200 ease-out" value={42} />
<NumberFlow motion="600 cubic-bezier(0.16, 1, 0.3, 1)" value={42} />
<NumberFlow motion="off" value={42} />
```

"prefers-reduced-motion: reduce" overrides every value. Third-party motion libraries that write inline styles to the element disable the internal transition automatically.

### Using your own animation library [#using-your-own-animation-library]

Attach GSAP, Framer Motion, or the Web Animations API by writing inline styles to the element. The component detects the first external write and disables its own CSS transition automatically.

## API Reference [#api-reference]

<PropsTable rows={[{"name":"value","type":"number","description":"The number to display. Animates on change."},{"name":"format","type":"Intl.NumberFormatOptions","description":"Formatting options passed to Intl.NumberFormat."},{"name":"locales","type":"Intl.LocalesArgument","description":"Locale tag or array for Intl.NumberFormat."},{"name":"prefix","type":"string","description":"Text rendered before the number."},{"name":"suffix","type":"string","description":"Text rendered after the number."},{"name":"motion","type":"string","description":"Duration plus optional easing. Pass off to disable."},{"name":"className","type":"string","description":"Additional classes merged with cn()."}]} />

## Accessibility [#accessibility]

- The outer element carries `aria-label` with the fully formatted value, so screen readers announce the number as a whole.
- Decorative spans are `aria-hidden="true"`.
- `prefers-reduced-motion: reduce` disables the slot transition.

## Best Practices [#best-practices]

- **Keep values short.** Two to six digits animate cleanly.
- **Prefer prefix and suffix over concatenation.** Keeps screen reader announcements readable.
- **Use motion off when changing values rapidly.**

## Related Components [#related-components]

- [Credit Card](/docs/modules/credit-card) — animated card surface with locale-aware numbers
- [Pulse](/docs/modules/pulse) — animated status indicator