# Animated Number

Number that moves to each new value as a calm count-up or a roll where only the changed digits turn, set in type or in dot-matrix LEDs whose dots switch on in place. Screen readers announce just the final value, not every step.

> Primitive · Free · Data Display — React Native, Expo Go compatible.

## Install

```bash
npx @lumioui/cli add animated-number
```

## Import

```tsx
import { ROLL_STAGGER, RollingText, AnimatedNumber } from "@/components/ui/animated-number/animated-number";
```

## Variants

- `balance` — Balance: `npx @lumioui/cli add animated-number-balance`
- `led` — LED thermostat: `npx @lumioui/cli add animated-number-led`
- `stats` — Stats: `npx @lumioui/cli add animated-number-stats`

## Props

### RollingText

| Prop | Type | Notes |
| --- | --- | --- |
| `text` | `string` | The figure to show, already formatted ("$6,482.17"). |
| `direction?` | `1 | -1` | 1 = the value went up (digits rise into place), -1 = down. Default 1. |
| `className?` | `string` | Row container — placement only (margins, alignment). |
| `glyphClassName?` | `string` | Typography for every glyph (size, weight, ink). |
| `glyphStyle?` | `StyleProp<TextStyle>` | — |
| `minorFrom?` | `number` | Characters from this index on use `minorClassName` — cents set smaller. |
| `minorClassName?` | `string` | — |
| `instant?` | `boolean` | Swap without motion (e.g. animation turned off by the caller). |
| `onSettle?` | `() => void` | Fires on JS once the last changed column has settled. |

### AnimatedNumber

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `number` | Target value. |
| `from?` | `number` | Value the first count starts from. Default 0. |
| `duration?` | `number` | Count duration in ms for "ease". Default 1000. Ignored by "spring" and "roll". |
| `animation?` | `"ease" | "spring" | "roll"` | Motion style — "ease" (default) counts with the ease.out token over `duration` ms; "spring" counts on the spring.roll token; "roll" swaps each changed digit column in place, 30ms apart from the right. |
| `format?` | `(n: number) => string` | Format the displayed number. Default rounds and locale-formats. Runs on the JS thread. |
| `precision?` | `number` | Decimal places the count re-renders at. Defaults to the precision of `value` / `from` (an integer target re-renders once per whole number). Raise it if your `format` shows more decimals than the value carries. |
| `startOnView?` | `boolean` | Wait until the number is visible before the first count. Default true. |
| `onSettle?` | `() => void` | Fires on JS when a change has landed — the moment to hold, sheen or move on. |
| `className?` | `string` | Glyph typography (size, weight, ink). In "roll" mode it styles every column. |
| `containerClassName?` | `string` | "roll" and "led" — placement classes for the row of columns. |
| `face?` | `"type" | "led"` | "type" (default) sets the figure in the system font; "led" in dot-matrix LEDs. |
| `dot?` | `number` | "led" only — LED diameter in pt. Default 5. |
| `color?` | `string` | "led" only — lit colour. Default the theme ink. |
| `beatColor?` | `string` | "led" only — changed dots light in this colour for a beat, then settle.  `animation="roll"` only — the ease/spring count-up switches instantly every  frame, so it has no beat. |

Source: https://lumioui.com/components/animated-number