# Number shuffle

Roll digits as a numeric value changes.

## Usage

Import numberShuffle from @mielui/svelte/actions/number-shuffle. Attach it to a text-only element and pass value. Render the final formatted value as normal text for server rendering and accessibility. Keep icons and markup outside the animated element.

```svelte

<script lang="ts">
    import { numberShuffle } from '@mielui/svelte/actions/number-shuffle';
    import { Button } from '@mielui/svelte/components/button';

    let value = $state(72);
    const values = [72, 98, 104, 36];
    function updateValue() {
        value = values[(values.indexOf(value) + 1) % values.length];
    }
</script>

<div class="flex flex-col items-center gap-6">
    <span
        use:numberShuffle={{ value }}
        class="inline-block min-w-[3ch] text-center text-4xl tabular-nums"
    >
        {value}
    </span>
    <Button variant="secondary" onclick={updateValue}>Update value</Button>
</div>


```

## Formatted values

```svelte

<script lang="ts">
    import { numberShuffle } from '@mielui/svelte/actions/number-shuffle';
    import { Button } from '@mielui/svelte/components/button';

    let value = $state(1240.5);
    const currency = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' });
    function format(amount: number) {
        return currency.format(amount);
    }
</script>

<div class="flex flex-col items-center gap-6">
    <span
        use:numberShuffle={{ value, format }}
        class="inline-block min-w-[10ch] text-center text-3xl tabular-nums"
    >
        {format(value)}
    </span>
    <div class="flex gap-2">
        <Button
            variant="secondary"
            onclick={() => {
                value += 125.25;
            }}
        >
            Add $125.25
        </Button>
        <Button
            variant="outline"
            onclick={() => {
                value = 0;
            }}
        >
            Reset
        </Button>
    </div>
</div>


```

## API reference

| Option | Type | Default |

| --- | --- | --- |

| value | number | Required |

| format | (value: number) => string | String |

| duration | number | Twice the theme panel duration, fallback 480ms |

The action rolls from zero on mount and continues from the current value on interrupted updates. Reduced motion, disabled theme motion, and duration zero show the final value immediately. Visual digits are hidden from assistive technology. Removing the element cleans up animation and restores its styles.