Number tween

When to use #

Use it for

A figure updates and the change should be easy to follow.

Skip it when

The exact value must be readable at every instant.

Installation #

terminal

pnpm dlx shadcn@latest add https://caliperui.site/r/number-tween.json

Adds its 3 files to components/ui/, each with its own stylesheet, and installs their packages. No account needed. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage #

This is the code behind the preview above.

example.tsx

import { useState } from "react"
import { NumberTween } from "@/components/ui/number-tween"

const snapshots = [
  { revenue: 48210, users: 12480, rate: 0.0342, latency: 182 },
  { revenue: 51890, users: 13105, rate: 0.0361, latency: 171 },
  { revenue: 49340, users: 12920, rate: 0.0329, latency: 205 },
  { revenue: 1204, users: 98, rate: 0.5, latency: 12 },
];

export function NumberTweenDemo() {
  const [snap] = useState(0);
  const data = snapshots[snap];
  return (
    <NumberTween key="r" value={data.revenue} format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }} animateOnView />
  );
}

API reference #

NumberTween

component

PropTypeDefaultDescription

value *number—

formatNumberFormatOptions—

localestring"en-US"

prefixstring""

suffixstring""

durationnumber900Milliseconds for a full count. Small changes finish sooner.

animateOnViewbooleanfalseCount up from zero the first time the number scrolls into view.

classNamestring—

It is built on native elements and keeps aria-live and aria-hidden in step with state. Changes that matter are announced through a live region.

No custom key handling; Tab and the native activation keys do the work.

Motion #

It checks prefers-reduced-motion itself and settles immediately instead of travelling. Every state is still reachable.