mielui
Actions

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 value as its text so it is available before JavaScript loads. Use tabular numerals and reserve enough width for the expected values.

<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

Pass format to display decimals, separators, or units. Use the same formatter for the element's text. Keep icons and other markup outside the animated element.

Motion and accessibility

Entry starts at zero. Updates continue from the current value when interrupted. The visual digits are hidden from assistive technology, which reads the final text. Reduced motion and disabled theme motion show the final value immediately. Removing the element cleans up the animation.

API reference

numberShuffle is a Svelte action for a text-only HTMLElement. Pass a NumberShuffleOptions object.

  • value Required
    number

    The target value to display.

  • format
    ((value: number) => string)

    Formats each intermediate and final value.

    Default String

  • duration
    number

    Milliseconds. Defaults to twice the theme panel duration, with a 480ms fallback. Set zero to update immediately.