NumberFlow (React)

NumberFlow is a React component that animates transitions between numeric values, spinning individual digits in and out and re-flowing grouping/decimal characters the way an odometer would. Under the hood it wraps a framework-agnostic custom element (number-flow-lite) so the same core rendering and diffing logic is shared across the project’s React, Vue, and Svelte packages. It formats numbers with Intl.NumberFormat, so locale, currency, percentage, and compact-notation formatting all work out of the box while the animation layer only replays the parts of the number that actually changed.

Beyond the basic value transition, NumberFlow ships a NumberFlowGroup for synchronizing multiple counters that update together (e.g. a price and its per-unit breakdown), continuous/trend plugins for stock-ticker-style motion, and first-class SSR support so the initial render is not blank before hydration. It automatically respects prefers-reduced-motion and falls back to a plain text swap when the browser can’t animate, making it a practical fit for dashboards, pricing pages, and any UI element that needs to draw attention to a changing count without feeling gimmicky.

What You Get

• A drop-in <NumberFlow value={...} /> component that animates between any two numbers using Intl.NumberFormat options for locale, currency, and precision
• A NumberFlowGroup component for keeping multiple related counters visually synchronized during simultaneous updates
• Built-in respect for prefers-reduced-motion, with automatic fallback to non-animated rendering
• SSR-safe rendering via a shared custom-element core so the first paint already shows the correct formatted number
• Plugins (e.g. continuous/trend) for stock-ticker-like motion and directional animation cues
• Framework parity — the same core engine also powers @number-flow/vue and @number-flow/svelte packages in the same monorepo

Common Use Cases

• Animating price or total changes in checkout and cart summaries
• Live-updating dashboard KPIs, stats, and counters
• Stock ticker or crypto price displays with trend-aware motion
• Gamified UI elements like scores, streaks, or leaderboard positions

Under The Hood

Architecture - The monorepo (packages/number-flow, packages/react, packages/vue, packages/svelte) centers on a framework-agnostic custom element defined in number-flow/lite, which handles formatting a value into structured Data (via formatToData) and diffing/animating the DOM between renders. @number-flow/react’s NumberFlow.tsx registers a NumberFlowElement custom element subclass once, then wraps it in a class component (NumberFlowImpl) that uses getSnapshotBeforeUpdate/componentDidUpdate to call willUpdate()/didUpdate() around the custom element exactly when data changes, letting the underlying element manage the actual digit transition animations. A NumberFlowGroup context coordinates multiple instances so simultaneous updates animate in lockstep.

Tech Stack - Pure TypeScript, built with tsup and a pnpm workspace (pnpm-workspace.yaml). React support spans React 16-19 with explicit shims (isReact19 branches) to handle differences in custom-element attribute handling and JSON serialization of props between versions. The core relies on the standard Intl.NumberFormat API for locale/currency formatting rather than a bundled formatting library, keeping the dependency footprint minimal (only esm-env for browser detection).

Code Quality - The test-suites/wrapper directory contains a substantial Vitest suite (render, SSR, update, animated, group, nonce, hashes, can-animate) with snapshot fixtures per test, covering cross-framework behavior consistently. Code is compact and heavily commented at tricky workaround points (e.g. React 19 attribute-changed-callback differences), which aids maintainability given the DOM/React interop complexity involved.

API Design - The public API is intentionally small: a single <NumberFlow value={...} /> component with optional locales/format props mirroring Intl.NumberFormatOptions, plus a NumberFlowGroup wrapper for coordinated groups. Because formatting options map directly onto the standard Intl API, there is no bespoke format mini-language to learn, and the component works as a near drop-in replacement for a plain {value} render, keeping the barrier to adoption low.