Rolling Digits

Spring-animated digit counter with blur and scale.

Installation

npx shadcn@latest add @iconiq/rolling-digits

Props

RollingDigits

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

Default 80

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

startOnViewboolean

Default true

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

Default 2

Pixel gap between rendered characters in the digit row.

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

Default dynamic

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

enterStiffnessnumber

Default 170

Spring stiffness for incoming digit motion.

enterDampingnumber

Default 10

Spring damping for incoming digit motion.

exitStiffnessnumber

Default 170

Spring stiffness for outgoing digit motion.

exitDampingnumber

Default 15

Spring damping for outgoing digit motion.

enterYnumber

Default 32

Vertical offset in pixels used when a digit enters.

enterBlurnumber

Default 52

Peak blur in pixels applied when a digit enters.

enterScalenumber

Default 0.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.

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`.

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: motion.