Skip to content
Components

AnimatedNumber

Animated number that counts up like an odometer. A faithful port of Motion+'s AnimateNumber: each digit is a full 0–9 column that rolls through the intermediate numerals to its new value (a FLIP spring on y), the leading digit rolls up from zero as magnitude grows, and section widths animate so proportional fonts stay aligned. Formatting (grouping, fraction digits, currency, sign) comes from Intl.NumberFormat; the token duration / easing drive the timing, or pass transition for a bespoke curve/spring. Use prefix / suffix for units and currency so they align with the digits and fold into the single screen-reader announcement.

0

materials indexed

Usage

import { AnimatedNumber, AnimatedNumberProps, AnimatedNumberTrend } from "@instruments/materia-ui/components/animated-number";

Best practices

  • Needs ReducedMotionProvider in the app tree - it supplies the LazyMotion domMax features the digit roll and layout animations require, and its reducedMotion="user" makes the number snap to its final value for users who ask for less motion.

  • Use prefix/suffix for units and currency ($, /10), not sibling text nodes - they're layout-animated with the digits and folded into the one screen-reader announcement.

  • Reach for the duration/easing tokens over a raw transition - token timing keeps it in step with the rest of the motion system; drop to transition only for bespoke springs.

Props

PropTypeDefaultDescription
value(required)number

The number value to display and animate

duration"instant" | "quick" | "normal" | "moderate" | "slow"

Duration token from

easing"out" | "inOut" | "sheet"

Easing token from

maskedboolean

Wraps the digits in a blur-vignette mask so they fade in and out at the top/bottom (and left/right) clipping edges - softening the roll for large display numbers. Uses --mask-height (0.15em) and --mask-width (0.5em).

prefixstring

Static text rendered before the number, e.g. "$". Layout-animated.

suffixstring

Static text rendered after the number, e.g. "/10". Layout-animated.

localesIntl.LocalesArgument

BCP-47 locale(s) passed to Intl.NumberFormat.

formatNumberFormat

Intl.NumberFormat options (grouping, fraction digits, currency…).

transitionTransition

Overrides the token-derived timing entirely, applied to the digit roll, layout and opacity. Accepts any motion Transition (duration, delay, ease, spring). Prefer duration / easing for the common token-based cases.

trendAnimatedNumberTrend

Which way the digits roll. Omitted, they follow the sign of the change, so a count going up rolls up even across 9 to 0. Pass 1 or -1 to force a direction (say, from the user's action rather than the arithmetic).

Also exports

  • interfaceAnimatedNumberProps
  • typeAnimatedNumberTrend

Composition

Builds on

VisuallyHidden

Used by

ThinkingLoader