For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Number Flow

A numeric slot machine built on Intl.NumberFormat, with custom motion support.

Web
Frakment
number-flow.tsx
"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

Usage

number-flow.tsx
import { NumberFlow } from "@/components/ui/number-flow";
number-flow.tsx
<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.

number-flow-format.tsx
"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>
  );
}
tsx
<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.

default (900ms)
200 ease-out
off
number-flow-motion.tsx
"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>
  );
}
ValueResult
omitted900ms "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
tsx
<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

PropTypeDefaultDescription
valuenumber—The number to display. Animates on change.
formatIntl.NumberFormatOptions—Formatting options passed to Intl.NumberFormat.
localesIntl.LocalesArgument—Locale tag or array for Intl.NumberFormat.
prefixstring—Text rendered before the number.
suffixstring—Text rendered after the number.
motionstring—Duration plus optional easing. Pass off to disable.
classNamestring—Additional classes merged with cn().

Accessibility

  • The outer element carries aria-label with the fully formatted value, so screen readers announce the number as a whole.
  • Decorative spans are aria-hidden="true".
  • prefers-reduced-motion: reduce disables 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.
  • Credit Card — animated card surface with locale-aware numbers
  • Pulse — animated status indicator