Animated Number

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Rolling numbers are Text value mode from @prepared911/ui/text. Pass value instead of children. Digits roll to each new value. from is the entrance number, roll={false} renders plain formatted text, and announcement is the polite live copy after a change settles.

Props

Name	Type	Default	Description
`align`	`TextAlign`	—	Inline-axis alignment.
`announcement`	`LocalizedMessage`	—	Absent in this mode. Belongs to value mode. Localized copy a polite live region announces after the roll settles. Not announced on first paint or for the entrance from `from`. Without it nothing is announced; the formatted value is still readable as text.
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-label`	`LocalizedMessage`	—	Accessible name when the visible label is insufficient.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`as`	`"span" \| "p" \| "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "strong" \| "em" \| "code"`	—	Element to render. Defaults to `span`. The visual role never picks the heading level.
`children`	`ReactNode`	—	Content rendered inside the element. Rejected in this mode: the number is the content. Pass `children` instead of `value` for other content.
`className`	`string`	—	Classes appended after the generated classes. Put overrides in `@layer chroma.overrides`.
`foreground`	`Foreground`	—	Foreground color. Defaults to {@link Foreground.Default}.
`formatOptions`	`NumberFormatOptions`	—	Absent in this mode. Belongs to value mode. `Intl.NumberFormat` options, formatted by the design system's number formatter: currency, percent, units, compact notation, fraction digits and sign display.
`from`	`number`	—	Absent in this mode. Belongs to value mode. Entrance: the first paint shows `from`, then the digits roll to `value`. Omitted, the first paint shows `value` with no motion. Read on mount only.
`identifier`	`boolean`	`false`	Marks the run as an identifier that must read the same in every language: a unit or incident id, a call sign, a phone number, a code, a phrase the user must type. Renders `translate="no"` so browser page translation leaves it as written, and wins over a `translate` passed alongside it. Pair it with `as="code"` or a `dir="ltr"` run (ADR 0019).
`instant`	`boolean`	`false`	Absent in this mode. Belongs to value mode. Columns follow the value with no motion. For a number that shows a live draft, such as an input being typed in.
`lineClamp`	`TextLineClamp`	—	Multi-line ellipsis clamp. Mutually exclusive with `truncate`.
`locale`	`string`	—	Absent in this mode. Belongs to value mode. BCP 47 locale for formatting and for the digit glyphs. Defaults to the runtime locale, so a server-rendered app that must match the client passes it explicitly.
`nowrap`	`boolean`	—	Keeps copy on one line without ellipsis.
`numerals`	`Numerals`	—	Numeral rendering. Defaults to {@link Numerals.Proportional}. Value mode always renders tabular numerals.
`prefix`	`TextAffix`	—	Absent in this mode. Belongs to value mode. Localized copy before the number, or a function of the value that returns it. Include any separating space in the copy. Each character is its own column, keyed by its distance from the number.
`ref`	`Ref<TextHost<T>>`	—	Ref to the rendered element.
`roll`	`boolean`	`true`	Absent in this mode. Belongs to value mode. Roll the digits to each new value. `false` renders the formatted number as plain text.
`suffix`	`TextAffix`	—	Absent in this mode. Belongs to value mode. Localized copy after the number, or a function of the value that returns it, such as a unit that pluralizes. Include any separating space in the copy. Each character is its own column, so `seat` to `seats` opens only the new `s`.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.
`truncate`	`boolean`	—	Single-line ellipsis when inline space is constrained. Sets `title` from children when `title` is omitted. Mutually exclusive with `lineClamp`.
`type`	`TextType`	—	Chroma typography role. Defaults to {@link TextType.BodyLarge}.
`value`	`number`	—	Absent in this mode. Pass `value` instead of `children` to show a number. The number to show. Each change rolls the digits that changed.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Basic animation

Polite announcement

The formatted value stays readable as text. announcement is spoken after the roll settles, not on first paint.

Static number

roll={false} skips the reel and renders the formatted number as plain text.

Import

Import Text and TextType from @prepared911/ui/text. There is no AnimatedNumber export.

Animated Number / Usage

Animated Number / Accessibility

On this page

Animated Number

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Props

Name	Type	Default	Description
`align`	`TextAlign`	—	Inline-axis alignment.
`announcement`	`LocalizedMessage`	—	Absent in this mode. Belongs to value mode. Localized copy a polite live region announces after the roll settles. Not announced on first paint or for the entrance from `from`. Without it nothing is announced; the formatted value is still readable as text.
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-label`	`LocalizedMessage`	—	Accessible name when the visible label is insufficient.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`as`	`"span" \| "p" \| "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "strong" \| "em" \| "code"`	—	Element to render. Defaults to `span`. The visual role never picks the heading level.
`children`	`ReactNode`	—	Content rendered inside the element. Rejected in this mode: the number is the content. Pass `children` instead of `value` for other content.
`className`	`string`	—	Classes appended after the generated classes. Put overrides in `@layer chroma.overrides`.
`foreground`	`Foreground`	—	Foreground color. Defaults to {@link Foreground.Default}.
`formatOptions`	`NumberFormatOptions`	—	Absent in this mode. Belongs to value mode. `Intl.NumberFormat` options, formatted by the design system's number formatter: currency, percent, units, compact notation, fraction digits and sign display.
`from`	`number`	—	Absent in this mode. Belongs to value mode. Entrance: the first paint shows `from`, then the digits roll to `value`. Omitted, the first paint shows `value` with no motion. Read on mount only.
`identifier`	`boolean`	`false`	Marks the run as an identifier that must read the same in every language: a unit or incident id, a call sign, a phone number, a code, a phrase the user must type. Renders `translate="no"` so browser page translation leaves it as written, and wins over a `translate` passed alongside it. Pair it with `as="code"` or a `dir="ltr"` run (ADR 0019).
`instant`	`boolean`	`false`	Absent in this mode. Belongs to value mode. Columns follow the value with no motion. For a number that shows a live draft, such as an input being typed in.
`lineClamp`	`TextLineClamp`	—	Multi-line ellipsis clamp. Mutually exclusive with `truncate`.
`locale`	`string`	—	Absent in this mode. Belongs to value mode. BCP 47 locale for formatting and for the digit glyphs. Defaults to the runtime locale, so a server-rendered app that must match the client passes it explicitly.
`nowrap`	`boolean`	—	Keeps copy on one line without ellipsis.
`numerals`	`Numerals`	—	Numeral rendering. Defaults to {@link Numerals.Proportional}. Value mode always renders tabular numerals.
`prefix`	`TextAffix`	—	Absent in this mode. Belongs to value mode. Localized copy before the number, or a function of the value that returns it. Include any separating space in the copy. Each character is its own column, keyed by its distance from the number.
`ref`	`Ref<TextHost<T>>`	—	Ref to the rendered element.
`roll`	`boolean`	`true`	Absent in this mode. Belongs to value mode. Roll the digits to each new value. `false` renders the formatted number as plain text.
`suffix`	`TextAffix`	—	Absent in this mode. Belongs to value mode. Localized copy after the number, or a function of the value that returns it, such as a unit that pluralizes. Include any separating space in the copy. Each character is its own column, so `seat` to `seats` opens only the new `s`.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.
`truncate`	`boolean`	—	Single-line ellipsis when inline space is constrained. Sets `title` from children when `title` is omitted. Mutually exclusive with `lineClamp`.
`type`	`TextType`	—	Chroma typography role. Defaults to {@link TextType.BodyLarge}.
`value`	`number`	—	Absent in this mode. Pass `value` instead of `children` to show a number. The number to show. Each change rolls the digits that changed.