Studio
2

Number shuffle

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

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

value

Required number. The target value to display.

format

Optional (value: number) => string formatter. Defaults to String.

duration

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