# Rolling Number

> A number whose digits roll to each new value, each one the way the whole value moved, so a value that changes during a scrub or a step reads as one number moving.

- Name: `rolling-number`
- Status: beta
- Categories: motion, display
- File: the install writes `rolling-number.tsx` to your `ui` alias, `@/components/ui` by default.
- Gallery: https://arbokui.com/components/rolling-number
- Registry item: https://arbokui.com/r/rolling-number.json

## Install

1. Add the registry to `components.json`. Do this first, once:

   ```bash
   npx shadcn@latest registry add "@arbokui=https://arbokui.com/r/{name}.json"
   ```

   The command writes this entry. You can also add it by hand:

   ```json
   {
     "registries": {
       "@arbokui": "https://arbokui.com/r/{name}.json"
     }
   }
   ```

   Without this step, the shadcn CLI looks up `@arbokui` in a public list that Arbokui does not control.

2. Add the theme once per app. It replaces your color tokens with ones checked for contrast:

   ```bash
   npx shadcn@latest add @arbokui/theme
   ```

3. Add the component:

   ```bash
   npx shadcn@latest add @arbokui/rolling-number
   ```

## Use it for

- A number that changes while a hover, scrub, or step is still going: a chart reading, a calendar tip, a stepper, a live count.
- Pass value. Pass format to print it another way, like { style: "currency", currency: "USD" }.
- Set its size and weight with className. It uses tabular digits, so the width holds while it rolls. A digit it gains or drops folds in or out, so the words beside it glide.

## Avoid it for

- A number that never changes. Print it as text.
- A value people need to read every step of, like a countdown. It shows only the end of each roll.
- Long text with digits in it, like a phone number. Only numbers roll.

## Props

- `value`: `number`. Required. The number to show. When it changes, each digit rolls to its new value.
- `format`: `Intl.NumberFormatOptions | ((value: number) => string)`. Default `{ maximumFractionDigits: 0 }`. How the number prints. Options work from a server component. A function works from a client component only.
- `locale`: `string`. Default `"en-US"`. The locale for format options. Fixed, so server and browser print the same text.
- `className`: `string`. Extra classes, like text size and weight. Later classes win.

## Accessibility

- Screen readers hear the final value only, as plain text. The rolling digits are hidden from them.
- It is not a live region. If a change must be announced, say it elsewhere.
- Each digit rolls over --motion-duration-slow on --motion-ease-spring. Reduced motion jumps straight to the new value, and so does motion off.

## Examples

### A count

```tsx
<RollingNumber value={1284} />
```

### Money

```tsx
<RollingNumber value={4173.5} format={{ style: "currency", currency: "USD" }} className="text-2xl font-semibold" />
```

### Following a slider

```tsx
const [value, setValue] = useState(40);

<RollingNumber value={value / 100} format={{ style: "percent" }} />
<Slider aria-label="Share" value={value} onValueChange={(next) => setValue(next as number)} />
```