Rolling Digits

Spring-animated digit counter with blur and scale.

Installation

npx shadcn@latest add @iconiq/rolling-digits

Props

RollingDigits

17 props

Inline animated counter that swaps digits with spring-driven blur, scale, and vertical motion while exiting the previous character.

valuenumber

Required

Target number to display. The component rounds to the nearest integer before formatting.

padnumber

Minimum digit width passed to `String.padStart`. Useful for clock-style or fixed-width counters.

animationDelaynumber

Default80

Milliseconds between queued value steps when `value` changes faster than the animation can finish.

startOnViewboolean

Defaulttrue

When true, playback waits until the component enters the viewport once before animating from zero.

localeboolean

When true, formats the rounded value with `toLocaleString()` before splitting digits.

format(value: number) => string

Custom formatter that runs before padding. Overrides `locale` when both are provided.

gapnumber

Default2

Pixel gap between rendered characters in the digit row.

direction"dynamic" | "up" | "down"

Defaultdynamic

Controls whether incoming digits slide up or down. `dynamic` compares the previous and next digit values.

enterStiffnessnumber

Default170

Spring stiffness for incoming digit motion.

enterDampingnumber

Default10

Spring damping for incoming digit motion.

exitStiffnessnumber

Default170

Spring stiffness for outgoing digit motion.

exitDampingnumber

Default15

Spring damping for outgoing digit motion.

enterYnumber

Default32

Vertical offset in pixels used when a digit enters.

enterBlurnumber

Default52

Peak blur in pixels applied when a digit enters.

enterScalenumber

Default0.7

Starting scale applied when a digit enters.

classNamestring

Merged onto the outer inline-flex span that wraps the readable and visual layers.

digitClassNamestring

Merged onto each animated digit cell wrapper for per-digit styling.

Notes

Non-digit characters from locale separators or custom formatters render as static spans and do not animate.

The visual layer is `aria-hidden`; screen readers receive the formatted number through an `sr-only` span.

When `startOnView` is enabled, the ticker displays zero until the container crosses the viewport threshold (`once: true`, `amount: 0.6`).

Each digit keeps a short exit queue so the previous character can blur and slide out while the next one springs into place.

Layer symbols such as `%` or `$` beside the component in your layout, or include them through `format`.