# RollingNumber
Package: @mantine/core
Import: import { RollingNumber } from '@mantine/core';
Description: Animate value changes with rolling digits

## Usage

`RollingNumber` animates value changes, each digit rolls to its new position independently:

```tsx
import { useState } from 'react';
import { Button, Group, RollingNumber } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState(1234);

  return (
    <>
      <RollingNumber value={value} fz="36px" />
      <Group mt="md">
        <Button onClick={() => setValue((v) => v + 1)}>Increment</Button>
        <Button onClick={() => setValue((v) => v - 1)}>Decrement</Button>
        <Button onClick={() => setValue(Math.floor(Math.random() * 10000))}>Random</Button>
      </Group>
    </>
  );
}
```


## Prefix and suffix

Set `prefix` and `suffix` props to add static text before or after the animated number.
Use `thousandSeparator` to separate thousands and `decimalScale` with `fixedDecimalScale`
to control decimal formatting:

```tsx
import { useState } from 'react';
import { Button, Group, RollingNumber } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState(99.99);

  return (
    <>
      <RollingNumber
        value={value}
        prefix="$ "
        suffix=" USD"
        decimalScale={2}
        fixedDecimalScale
        thousandSeparator
        fz="32px"
      />
      <Group mt="md">
        <Button onClick={() => setValue((v) => +(v + 10.5).toFixed(2))}>+10.50</Button>
        <Button onClick={() => setValue((v) => +(v - 10.5).toFixed(2))}>-10.50</Button>
        <Button onClick={() => setValue(+(Math.random() * 10000).toFixed(2))}>Random</Button>
      </Group>
    </>
  );
}
```


## Animation duration

Set `animationDuration` (in milliseconds) and `timingFunction` props to change the animation:

```tsx
import { useState } from 'react';
import { Button, Group, RollingNumber, Stack, Text } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState(500);

  return (
    <Stack>
      <div>
        <Text size="sm">200ms</Text>
        <RollingNumber value={value} animationDuration={200} fz="28px" />
      </div>
      <div>
        <Text size="sm">600ms (default)</Text>
        <RollingNumber value={value} animationDuration={600} fz="28px" />
      </div>
      <div>
        <Text size="sm">1200ms</Text>
        <RollingNumber value={value} animationDuration={1200} fz="28px" />
      </div>
      <Group>
        <Button onClick={() => setValue(Math.floor(Math.random() * 1000))}>Random</Button>
      </Group>
    </Stack>
  );
}
```


## Text selection and copying

Selecting and copying `RollingNumber` always produces the value as it is displayed,
for example `$ 1,234.56 USD`.

## Accessibility

Set `withLiveRegion` when screen readers should announce changes to the number:

```tsx
import { RollingNumber } from '@mantine/core';

function ResultCount({ count }: { count: number }) {
  return <RollingNumber value={count} withLiveRegion />;
}
```


#### Props

**RollingNumber props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| animationDuration | number | 600 | Animation duration in milliseconds |
| decimalScale | number | - | Number of decimal places to display |
| decimalSeparator | string | '.' | Character used as a decimal separator |
| fixedDecimalScale | boolean | false | If set, trailing zeros are added to match `decimalScale` |
| prefix | string | - | Prefix added before the value |
| suffix | string | - | Suffix added after the value |
| tabularNumbers | boolean | true | If set, use tabular (monospace) numbers |
| thousandSeparator | string \| boolean | false | Character used to separate thousands, set to `true` for `,` |
| timingFunction | string | 'ease' | CSS timing function for animation |
| value | number | required | Number value to display |
| withLiveRegion | boolean | false | If set, the root element acts as an `aria-live="polite"` region (`role="status"`) with the formatted value as its text content, so screen readers announce value changes. When `false`, the root uses `role="img"` with the value in `aria-label` so the current value is still accessible but updates are not announced. |


#### Styles API

RollingNumber component supports Styles API. With Styles API, you can customize styles of any inner element. Follow the documentation to learn how to use CSS modules, CSS variables and inline styles to get full control over component styles.

**RollingNumber selectors**

| Selector | Static selector | Description |
|----------|----------------|-------------|
| root | .mantine-RollingNumber-root | Root element |
| inner | .mantine-RollingNumber-inner | Wrapper of the value, keeps digits and characters in left-to-right order |
| digit | .mantine-RollingNumber-digit | Wrapper of a single digit, clips the digits column |
| digitColumn | .mantine-RollingNumber-digitColumn | Column of digits inside `digit`, animated on value change |
| char | .mantine-RollingNumber-char | Non-digit part of the value: prefix, suffix, minus sign, decimal and thousands separators |

**RollingNumber CSS variables**

| Selector | Variable | Description |
|----------|----------|-------------|
| root | --rn-duration | Controls animation duration |
| root | --rn-timing-function | Controls animation timing function |

**RollingNumber data attributes**

| Selector | Attribute | Condition | Value |
|----------|-----------|-----------|-------|
| root | data-tabular-numbers | `tabularNumbers` prop is set | - |
