Prepared Docs

Overview

AnimatedNumber formats and animates a numeric value with NumberFlow. The animation runtime lazy-loads; Suspense and chunk failures degrade to the same formatted static value CoreText would render. CoreText stays static-only; use this primitive whenever a number should roll between values.

When to use

KPI values that update in place (MetricCard, dashboards, counters).
Magnitude deltas that should visually roll without stealing the card's polite announcement.
Any numeric readout that already uses NumericDisplay or NumericCompact typography.

When not to use

Plain labels, headings, or prose: use Text.
Non-numeric content or pre-localized strings that are not numbers.
Entire card activation: use MetricCard or Card.

Variants

Prop	Purpose
`type`	Typography ladder; defaults to `NumericDisplay`.
`from`	Optional entrance start; omission snaps first paint to `value`.
`duration`	Milliseconds; `@default` 900. Zero or reduced motion snaps.
`live` / `announcement`	Polite live region for the settled value only.

Anatomy

Inline span root with tabular figures. NumberFlow renders the visual value in a shadow-DOM custom element with a persistent parent-edge alpha mask; settled glyphs remain unobscured while moving digits fade at the top and bottom edges. The formatted screen-reader layer remains the single semantic source.

Content guidelines

Pair polite announcements with localized copy that describes the settled value, not every intermediate digit.
Keep formatOptions aligned with product number conventions; locale changes snap and reformat.

Behavior and states

Reduced motion snaps immediately without scheduling animation frames.
Retargeting mid-flight follows NumberFlow's continuous carry behavior; polite announcements wait for animation finish.
Initial paint is silent in the live region; only later settled changes announce when live="polite".
The root reserves the typography line box so lazy load and NumberFlow settle do not change the parent height.

Best practices

Do put spoken KPI wording on the MetricCard value announcement, not on delta magnitudes.
Do rely on NumberFlow's built-in parent mask rather than custom per-digit fades.
Don't animate non-finite values; they render as static strings.
Don't reintroduce odometer props on CoreText.

Text for static typography.
MetricCard for the KPI preset.

Tokens

Animated Number / API and Development

Overview

When to use

KPI values that update in place (MetricCard, dashboards, counters).
Magnitude deltas that should visually roll without stealing the card's polite announcement.
Any numeric readout that already uses NumericDisplay or NumericCompact typography.

When not to use

Plain labels, headings, or prose: use Text.
Non-numeric content or pre-localized strings that are not numbers.
Entire card activation: use MetricCard or Card.

Variants

Prop	Purpose
`type`	Typography ladder; defaults to `NumericDisplay`.
`from`	Optional entrance start; omission snaps first paint to `value`.
`duration`	Milliseconds; `@default` 900. Zero or reduced motion snaps.
`live` / `announcement`	Polite live region for the settled value only.

Anatomy

Content guidelines

Pair polite announcements with localized copy that describes the settled value, not every intermediate digit.
Keep formatOptions aligned with product number conventions; locale changes snap and reformat.

Behavior and states

Reduced motion snaps immediately without scheduling animation frames.
Retargeting mid-flight follows NumberFlow's continuous carry behavior; polite announcements wait for animation finish.
Initial paint is silent in the live region; only later settled changes announce when live="polite".
The root reserves the typography line box so lazy load and NumberFlow settle do not change the parent height.

Best practices

Do put spoken KPI wording on the MetricCard value announcement, not on delta magnitudes.
Do rely on NumberFlow's built-in parent mask rather than custom per-digit fades.
Don't animate non-finite values; they render as static strings.
Don't reintroduce odometer props on CoreText.