Animated Number · Tinyrack Design System

Contract

TRAnimatedNumber displays a number supplied by application state. It does not own a timer or counter. The default roll animation moves changed digits in the value trend, while count interpolates the numeric value before applying the same locale-aware format. The first render is static so server rendering and hydration show the final value immediately.

Axis	Values	Default
`animation`	`roll`, `count`	`roll`
`duration`	non-negative milliseconds	`600`
`rollDirection`	`auto`, `up`, `down`	`auto`
`format`	`Intl.NumberFormatOptions`	decimal format
`locale`	`Intl.LocalesArgument`	runtime locale

Install

pnpm add @tinyrack/ui

Scroll inside the code area to read long lines.

Styles

@import '@tinyrack/ui/components/animated-number.css';

Scroll inside the code area to read long lines.

Imports

import { TRAnimatedNumber } from '@tinyrack/ui/components/animated-number';

Scroll inside the code area to read long lines.

Playground

1,248

Usage

Changing metric permalink

Update the controlled value to roll each changed digit in the overall value direction.

1,248

Examples

Roll and count permalink

Use roll when individual digit movement matters. Use count when the path between two numeric values should remain visible.

42roll42count

Locale-aware formats permalink

Currency, percent, unit, grouping, signs, and decimal characters come from Intl.NumberFormat.

currency$1,234.50percent12.3%unit1,234.5 GB

Forced roll direction permalink

Keep auto for ordinary metrics. Force up or down when the visual direction has domain meaning, such as a countdown-style display.

10up10down

API

value is required. Updating it starts the selected animation; mounting the component does not animate from zero.
animation="roll" aligns integer digits from the right and fractional digits from the left. rollDirection affects only this mode. animation="count" formats the eased intermediate numeric value on each frame.
duration controls both modes in milliseconds. 0 and negative values settle immediately; a non-finite duration falls back to 600.
format and locale are passed to Intl.NumberFormat. Changing either setting settles the current value immediately instead of animating between incompatible formats. NaN and infinite values are also displayed without animation.
The visual digit layers are hidden from assistive technology, leaving one formatted text value. Changes are not live announcements by default. Pass native aria-live with the value polite only when the update should be announced.
When prefers-reduced-motion is reduce, active movement is canceled and the final value is preserved. Native span props, event handlers, styles, class names, and React 19 refs are forwarded.

CSS token	Default	Purpose
`--tr-animated-number-duration`	`--tinyrack-duration-number`	Roll and character transition duration when the `duration` prop is omitted
`--tinyrack-duration-number`	`600ms`	Foundation timing for readable number transitions