Skip to content

NumberFlow Grid Notes

Dependency-free animated number component for React, Vue and Svelte that rolls individual digits into place and formats values with `Intl.NumberFormat`.

Grid NotesVersion 0.6.xMotionChecked 2026-11-06
Setup & agent config

Install and prerequisites

What your agent should install or configure before writing code with this pack.
Terminal
npm install @number-flow/react
Packages:@number-flow/react

Works with React 18 and 19. Uses CSS transforms and custom elements internally with zero external runtime dependencies.

Framework setup

Production-ready wiring for React 19, Next.js App Router and Tailwind CSS v4.

Animated metric or price counter with Intl formatting

Pass numeric value and standard Intl.NumberFormatOptions in format; wrap related counters in <NumberFlowGroup> so adjacent layout shifts sync.

components/price-counter.tsx
"use client";

import NumberFlow, { NumberFlowGroup } from "@number-flow/react";

export function PriceCounter({ amount, delta }: { amount: number; delta: number }) {
  return (
    <NumberFlowGroup>
      <div className="flex items-baseline gap-2 tabular-nums">
        <NumberFlow
          value={amount}
          format={{ style: "currency", currency: "USD", trailingZeroDisplay: "stripIfInteger" }}
          className="text-2xl font-semibold"
        />
        <NumberFlow
          value={delta}
          format={{ style: "percent", signDisplay: "always", maximumFractionDigits: 1 }}
          className="text-sm"
        />
      </div>
    </NumberFlowGroup>
  );
}

Gotchas for agents

Real-world traps — version mismatches, licence boundaries, main-thread stalls and CSS layer rules — that trip AI agents up.
  1. Never animate numbers the user is actively typing

    Rolling digits on an input readout or live calculator while someone types introduces visual lag. Use NumberFlow for discrete state changes (billing period toggles, filter counts, dashboard ticks), not keystroke-by-keystroke field echoes.

  2. Unsupported Intl notations and scripts

    Scientific and engineering notation (notation: 'scientific' | 'engineering'), non-Latin numbering systems, and right-to-left (rtl) digit layouts are not supported; fall back to plain Intl.NumberFormat for those locales.

  3. Keep tabular-nums on surrounding text

    Set tabular-nums (font-variant-numeric: tabular-nums) on the counter and its container so surrounding labels don't jitter horizontally while digits spin.

Accessibility and reduced motion

How to keep animations and interactive components accessible across keyboard, screen readers and prefers-reduced-motion.

Reduced motion

respectMotionPreference is true by default: under prefers-reduced-motion: reduce, digit spin animations are skipped and values update immediately.

Keyboard and screen readers

NumberFlow renders an accessible text representation alongside the visual digit wheels so screen readers read the full formatted number rather than individual spinning digits.