Dither number

Installation

Usage

Copyimport { DitherNumber } from "@/components/dithercn/dither-number";
 
export function Stat() {
  return <DitherNumber value={128406} size="xl" />;
}

When the number scrolls into view, every digit moves from from (0 by default) to its place in value. Change value later and only the digits that differ move, left to right, stagger milliseconds apart. While a digit moves it takes the accent colour, then fades back to the number's colour as it lands.

There are two effects:

• roll spins each digit on a strip, up when the value grows and down when it shrinks. The top and bottom of each digit's window dither out, so digits fade in and out of the line instead of being cut off. A place that moves by ten or more spins a full extra turn, like a mechanical counter.
• resolve turns the old digit into the new one cell by cell. The two use complementary dither masks, so each cell shows one digit or the other and they never blur together.

Digits are tabular, so the width only changes when the number of digits does. Separators, currency symbols, the prefix and the suffix keep their natural width and never move.

Examples

KPI tiles

A dashboard row whose values update every few seconds. size="sm", a muted suffix through affixClassName, and resolve and roll side by side. The latency tile uses an orange accent.

Landing stat

size="display" scales with the viewport. A longer duration and stagger make the first roll feel heavier; after that, the counter ticks up live and only the last few digits move.

Props

Notes

• The formatted value, with its prefix and suffix, is real text laid over the animation and made transparent, so it can be selected and copied and is what screen readers and search engines read. The moving digits are hidden from assistive technology. For a value that updates live, add aria-live="polite" yourself.
• The number sets line-height: 1.1 so the dithered fade has room above and below the digits. A tighter leading-* class works, but the fade may touch the tops of tall glyphs.
• The server renders the final value. On the client the digits wait at from until the trigger fires.
• With reduced motion turned on, the number changes instantly.
• Only ASCII digits animate. Formats that use another numbering system show their digits without motion.