- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
"use client";
import { useEffect, useRef } from "react";
import { useMotionGuard, useReducedMotion } from "@/lib/motion";
import { cn } from "@/lib/utils";
const DEFAULT_DURATION = 900;
const DEFAULT_EASING = "cubic-bezier(0.2, 0, 0.2, 1)";
const STYLE_ID = "frakment-nf-style";
const MASK = "0.15em";
const STYLES = [
".frakment-nf{display:inline-block;direction:ltr;white-space:nowrap;line-height:1}",
".frakment-nf .digit{display:inline-block;position:relative;width:0.6em;height:1em;overflow:hidden;vertical-align:top;-webkit-mask-image:linear-gradient(to bottom,transparent 0,#000 " +
MASK +
",#000 calc(100% - " +
MASK +
"),transparent 100%);mask-image:linear-gradient(to bottom,transparent 0,#000 " +
MASK +
",#000 calc(100% - " +
MASK +
"),transparent 100%)}",
".frakment-nf .digit-num{display:block;position:absolute;top:0;left:0;width:100%;height:1em;text-align:center;line-height:1;will-change:transform}",
".frakment-nf .text{display:inline-block}",
"@keyframes nf-out-up{from{transform:translateY(0)}to{transform:translateY(-100%)}}",
"@keyframes nf-in-up{from{transform:translateY(100%)}to{transform:translateY(0)}}",
"@keyframes nf-out-down{from{transform:translateY(0)}to{transform:translateY(100%)}}",
"@keyframes nf-in-down{from{transform:translateY(-100%)}to{transform:translateY(0)}}",
].join("");
export interface NumberFlowProps {
className?: string;
format?: Intl.NumberFormatOptions;
locales?: Intl.LocalesArgument;
motion?: string;
prefix?: string;
suffix?: string;
value: number;
}
function parseMotionProp(motion: string | undefined) {
if (motion === undefined) {
return { duration: DEFAULT_DURATION, easing: DEFAULT_EASING };
}
const parts = motion.trim().split(/\s+/);
if (!parts[0]) {
return { duration: DEFAULT_DURATION, easing: DEFAULT_EASING };
}
const raw = parts[0];
const v = Number.parseFloat(raw);
let duration = DEFAULT_DURATION;
if (!Number.isNaN(v)) {
duration = /ms$/.test(raw) ? v : /s$/.test(raw) ? v * 1000 : v;
}
return { duration, easing: parts.slice(1).join(" ") || DEFAULT_EASING };
}
function Digit({
char,
duration,
easing,
reduce,
}: {
char: string;
duration: number;
easing: string;
reduce: boolean;
}) {
const curr = Number.parseInt(char, 10);
const prevRef = useRef(curr);
const prev = prevRef.current;
const changed = prev !== curr;
let delta = curr - prev;
if (delta > 5) {
delta -= 10;
} else if (delta < -5) {
delta += 10;
}
const dir = delta >= 0 ? "up" : "down";
const animKey = `${prev}-${curr}`;
useEffect(() => {
if (!changed) {
return;
}
const t = setTimeout(() => {
prevRef.current = curr;
}, duration);
return () => clearTimeout(t);
}, [changed, curr, duration]);
return (
<span className="digit">
{changed && !reduce && (
<span
className="digit-num"
key={`out-${animKey}`}
style={{
animation: `nf-out-${dir} ${duration}ms ${easing} forwards`,
}}
>
{prev}
</span>
)}
<span
className="digit-num"
key={`in-${animKey}`}
style={{
animation:
changed && !reduce
? `nf-in-${dir} ${duration}ms ${easing} forwards`
: "none",
}}
>
{curr}
</span>
</span>
);
}
function NumberFlow({
className,
format,
locales,
motion,
prefix,
suffix,
value,
}: NumberFlowProps) {
const ref = useRef<HTMLSpanElement>(null);
const reduce = useReducedMotion();
useEffect(() => {
if (typeof document === "undefined") {
return;
}
if (document.getElementById(STYLE_ID)) {
return;
}
const el = document.createElement("style");
el.id = STYLE_ID;
el.textContent = STYLES;
document.head.appendChild(el);
}, []);
const fingerprint = JSON.stringify({ motion });
const yielded = useMotionGuard(
ref,
motion !== undefined && !reduce,
fingerprint
);
const disabled = reduce || yielded || motion === "off";
const { duration, easing } = disabled
? { duration: 0, easing: "linear" }
: parseMotionProp(motion);
const formatted = new Intl.NumberFormat(locales, format).format(value);
const display = `${prefix ?? ""}${formatted}${suffix ?? ""}`;
return (
<span
aria-label={display}
className={cn("frakment-nf tabular-nums", className)}
ref={ref}
>
<span aria-hidden="true">
{prefix ? <span className="text">{prefix}</span> : null}
{formatted.split("").map((char, i) => {
const isDigit = char >= "0" && char <= "9";
if (isDigit) {
return (
<Digit
char={char}
duration={duration}
easing={easing}
key={i}
reduce={disabled}
/>
);
}
return (
<span className="text" key={i}>
{char}
</span>
);
})}
{suffix ? <span className="text">{suffix}</span> : null}
</span>
</span>
);
}
export { NumberFlow };Number Flow animates between numeric values with a vertical slot machine. Each digit slides into place when the value changes.
Installation
$ bunx --bun frakment add number-flow$ npx frakment add number-flow$ pnpm dlx frakment add number-flow$ yarn dlx frakment add number-flow
No external dependencies required.
Copy the source into your project.
"use client";
import { useEffect, useRef } from "react";
import { useMotionGuard, useReducedMotion } from "@/lib/motion";
import { cn } from "@/lib/utils";
const DEFAULT_DURATION = 900;
const DEFAULT_EASING = "cubic-bezier(0.2, 0, 0.2, 1)";
const STYLE_ID = "frakment-nf-style";
const MASK = "0.15em";
const STYLES = [
".frakment-nf{display:inline-block;direction:ltr;white-space:nowrap;line-height:1}",
".frakment-nf .digit{display:inline-block;position:relative;width:0.6em;height:1em;overflow:hidden;vertical-align:top;-webkit-mask-image:linear-gradient(to bottom,transparent 0,#000 " +
MASK +
",#000 calc(100% - " +
MASK +
"),transparent 100%);mask-image:linear-gradient(to bottom,transparent 0,#000 " +
MASK +
",#000 calc(100% - " +
MASK +
"),transparent 100%)}",
".frakment-nf .digit-num{display:block;position:absolute;top:0;left:0;width:100%;height:1em;text-align:center;line-height:1;will-change:transform}",
".frakment-nf .text{display:inline-block}",
"@keyframes nf-out-up{from{transform:translateY(0)}to{transform:translateY(-100%)}}",
"@keyframes nf-in-up{from{transform:translateY(100%)}to{transform:translateY(0)}}",
"@keyframes nf-out-down{from{transform:translateY(0)}to{transform:translateY(100%)}}",
"@keyframes nf-in-down{from{transform:translateY(-100%)}to{transform:translateY(0)}}",
].join("");
export interface NumberFlowProps {
className?: string;
format?: Intl.NumberFormatOptions;
locales?: Intl.LocalesArgument;
motion?: string;
prefix?: string;
suffix?: string;
value: number;
}
function parseMotionProp(motion: string | undefined) {
if (motion === undefined) {
return { duration: DEFAULT_DURATION, easing: DEFAULT_EASING };
}
const parts = motion.trim().split(/\s+/);
if (!parts[0]) {
return { duration: DEFAULT_DURATION, easing: DEFAULT_EASING };
}
const raw = parts[0];
const v = Number.parseFloat(raw);
let duration = DEFAULT_DURATION;
if (!Number.isNaN(v)) {
duration = /ms$/.test(raw) ? v : /s$/.test(raw) ? v * 1000 : v;
}
return { duration, easing: parts.slice(1).join(" ") || DEFAULT_EASING };
}
function Digit({
char,
duration,
easing,
reduce,
}: {
char: string;
duration: number;
easing: string;
reduce: boolean;
}) {
const curr = Number.parseInt(char, 10);
const prevRef = useRef(curr);
const prev = prevRef.current;
const changed = prev !== curr;
let delta = curr - prev;
if (delta > 5) {
delta -= 10;
} else if (delta < -5) {
delta += 10;
}
const dir = delta >= 0 ? "up" : "down";
const animKey = `${prev}-${curr}`;
useEffect(() => {
if (!changed) {
return;
}
const t = setTimeout(() => {
prevRef.current = curr;
}, duration);
return () => clearTimeout(t);
}, [changed, curr, duration]);
return (
<span className="digit">
{changed && !reduce && (
<span
className="digit-num"
key={`out-${animKey}`}
style={{
animation: `nf-out-${dir} ${duration}ms ${easing} forwards`,
}}
>
{prev}
</span>
)}
<span
className="digit-num"
key={`in-${animKey}`}
style={{
animation:
changed && !reduce
? `nf-in-${dir} ${duration}ms ${easing} forwards`
: "none",
}}
>
{curr}
</span>
</span>
);
}
function NumberFlow({
className,
format,
locales,
motion,
prefix,
suffix,
value,
}: NumberFlowProps) {
const ref = useRef<HTMLSpanElement>(null);
const reduce = useReducedMotion();
useEffect(() => {
if (typeof document === "undefined") {
return;
}
if (document.getElementById(STYLE_ID)) {
return;
}
const el = document.createElement("style");
el.id = STYLE_ID;
el.textContent = STYLES;
document.head.appendChild(el);
}, []);
const fingerprint = JSON.stringify({ motion });
const yielded = useMotionGuard(
ref,
motion !== undefined && !reduce,
fingerprint
);
const disabled = reduce || yielded || motion === "off";
const { duration, easing } = disabled
? { duration: 0, easing: "linear" }
: parseMotionProp(motion);
const formatted = new Intl.NumberFormat(locales, format).format(value);
const display = `${prefix ?? ""}${formatted}${suffix ?? ""}`;
return (
<span
aria-label={display}
className={cn("frakment-nf tabular-nums", className)}
ref={ref}
>
<span aria-hidden="true">
{prefix ? <span className="text">{prefix}</span> : null}
{formatted.split("").map((char, i) => {
const isDigit = char >= "0" && char <= "9";
if (isDigit) {
return (
<Digit
char={char}
duration={duration}
easing={easing}
key={i}
reduce={disabled}
/>
);
}
return (
<span className="text" key={i}>
{char}
</span>
);
})}
{suffix ? <span className="text">{suffix}</span> : null}
</span>
</span>
);
}
export { NumberFlow };Update the import paths.
Usage
import { NumberFlow } from "@/components/ui/number-flow";<NumberFlow value={1234} />Formatting
value goes through Intl.NumberFormat for locale-aware grouping, decimals, and percent. Pass format, locales, prefix, suffix to control the output.
"use client";
import { NumberFlow } from "@/components/ui/number-flow";
export function NumberFlowFormat() {
return (
<div className="flex flex-wrap items-center justify-center gap-x-8 gap-y-4 px-6 py-8 text-2xl font-semibold tabular-nums">
<NumberFlow format={{ style: "percent" }} value={0.125} />
<NumberFlow prefix="$" value={1234} />
<NumberFlow suffix=" km" value={1234} />
<NumberFlow locales="de-DE" value={1234} />
</div>
);
}<NumberFlow value={12.5} format={{ style: "percent" }} />
<NumberFlow value={1234} prefix="$" />
<NumberFlow value={1234} suffix=" km" />
<NumberFlow value={1234} locales="de-DE" />Motion
By default, each digit slides with a 900ms "cubic-bezier(0.2, 0, 0.2, 1)" transition. Pass "motion" to override duration and easing.
"use client";
import { useEffect, useState } from "react";
import { NumberFlow } from "@/components/ui/number-flow";
export function NumberFlowMotion() {
const [value, setValue] = useState(0);
useEffect(() => {
const id = setInterval(() => {
setValue((v) => (v + 1) % 100);
}, 1500);
return () => clearInterval(id);
}, []);
return (
<div className="grid grid-cols-3 items-center gap-6 px-6 py-8">
<div className="flex flex-col items-center gap-1">
<span className="text-muted-foreground text-xs font-medium">
default (900ms)
</span>
<div className="text-3xl font-semibold tabular-nums">
<NumberFlow value={value} />
</div>
</div>
<div className="flex flex-col items-center gap-1">
<span className="text-muted-foreground text-xs font-medium">
200 ease-out
</span>
<div className="text-3xl font-semibold tabular-nums">
<NumberFlow motion="200 ease-out" value={value} />
</div>
</div>
<div className="flex flex-col items-center gap-1">
<span className="text-muted-foreground text-xs font-medium">off</span>
<div className="text-3xl font-semibold tabular-nums">
<NumberFlow motion="off" value={value} />
</div>
</div>
</div>
);
}| Value | Result |
|---|---|
| omitted | 900ms "cubic-bezier(0.2, 0, 0.2, 1)" |
| "150" | 150ms default easing |
| "150ms" | 150ms default easing |
| "1s" | 1000ms default easing |
| "200 ease-out" | 200ms custom easing |
| "600 cubic-bezier(0.16, 1, 0.3, 1)" | 600ms custom cubic-bezier |
| "off" | No transition |
<NumberFlow motion="200 ease-out" value={42} />
<NumberFlow motion="600 cubic-bezier(0.16, 1, 0.3, 1)" value={42} />
<NumberFlow motion="off" value={42} />"prefers-reduced-motion: reduce" overrides every value. Third-party motion libraries that write inline styles to the element disable the internal transition automatically.
Using your own animation library
Attach GSAP, Framer Motion, or the Web Animations API by writing inline styles to the element. The component detects the first external write and disables its own CSS transition automatically.
API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
value | number | — | The number to display. Animates on change. |
format | Intl.NumberFormatOptions | — | Formatting options passed to Intl.NumberFormat. |
locales | Intl.LocalesArgument | — | Locale tag or array for Intl.NumberFormat. |
prefix | string | — | Text rendered before the number. |
suffix | string | — | Text rendered after the number. |
motion | string | — | Duration plus optional easing. Pass off to disable. |
className | string | — | Additional classes merged with cn(). |
Accessibility
- The outer element carries
aria-labelwith the fully formatted value, so screen readers announce the number as a whole. - Decorative spans are
aria-hidden="true". prefers-reduced-motion: reducedisables the slot transition.
Best Practices
- Keep values short. Two to six digits animate cleanly.
- Prefer prefix and suffix over concatenation. Keeps screen reader announcements readable.
- Use motion off when changing values rapidly.
Related Components
- Credit Card — animated card surface with locale-aware numbers
- Pulse — animated status indicator