{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "cavemio-number-roll", "title": "Number Roll", "description": "Numbers that move with their value. Each changing digit rolls into place, with support for currency, compact notation, and live counters.", "dependencies": [], "files": [ { "path": "registry/components/number-roll.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\n\n/* ─────────────────────────────────────────────────────────\n * NUMBER ROLL: numbers that change like an odometer\n *\n * rolling each digit is a column that rolls to its new\n * value, in the direction the number moved: going\n * up, a 9 rolls on to 0 instead of spinning back\n * places new places slide open from nothing; lost ones\n * fold away\n * format anything Intl.NumberFormat does: currency,\n * percent, compact (\"1.2K\"), decimals\n *\n * The real number is always there as text for screen readers\n * and copy and paste; the columns are only what you see.\n * ───────────────────────────────────────────────────────── */\n\nexport interface NumberRollProps extends Omit<\n React.HTMLAttributes,\n \"children\"\n> {\n value: number;\n /** Intl.NumberFormat options, e.g. { style: \"currency\", currency: \"USD\" }. */\n format?: Intl.NumberFormatOptions;\n locales?: string | string[];\n prefix?: string;\n suffix?: string;\n /** Start from this value and roll to `value` once mounted, e.g. 0 for stats. */\n from?: number;\n /** Roll duration in ms. */\n duration?: number;\n /** Always roll this way, e.g. \"down\" for a countdown's seconds, which wrap from 00 to 59. Defaults to the way the number moved. */\n direction?: \"up\" | \"down\";\n}\n\ntype Column = { key: string; char: string; digit: number | null };\n\nconst EASE = \"cubic-bezier(0.16,1,0.3,1)\";\nconst SETS = 5; // the strip repeats 0–9 five times so a roll never runs out of digits\nconst MIDDLE = 20;\n/** The strip as one text node, a digit a line: fifty lines, but one element to lay out instead of fifty. */\nconst STRIP = Array.from({ length: SETS * 10 }, (_, i) => i % 10).join(\"\\n\");\n\nconst reducedQuery = \"(prefers-reduced-motion: reduce)\";\nconst subscribeReduced = (onChange: () => void) => {\n const query = window.matchMedia(reducedQuery);\n query.addEventListener(\"change\", onChange);\n return () => query.removeEventListener(\"change\", onChange);\n};\nconst useReducedMotion = () =>\n React.useSyncExternalStore(\n subscribeReduced,\n () => window.matchMedia(reducedQuery).matches,\n () => false,\n );\n\n/** Digits are keyed by their place counted from the right, so the units column stays the units column. */\nfunction columns(text: string): Column[] {\n const chars = [...text];\n const seen = new Map();\n let place = 0;\n const out: Column[] = [];\n for (let i = chars.length - 1; i >= 0; i--) {\n const char = chars[i];\n if (/\\d/.test(char))\n out.push({ key: `d${place++}`, char, digit: Number(char) });\n else {\n // Symbols are keyed by how many of the same symbol sit to their right, so a comma that shifts is the same comma.\n const n = seen.get(char) ?? 0;\n seen.set(char, n + 1);\n out.push({ key: `s${char}${n}`, char, digit: null });\n }\n }\n return out.reverse();\n}\n\n// Memoised: a parent that re-renders with the same number doesn't rebuild the strips.\nconst Digit = React.memo(function Digit({\n digit,\n trend,\n duration,\n reduced,\n rollIn,\n}: {\n digit: number;\n trend: number;\n duration: number;\n reduced: boolean;\n rollIn: boolean;\n}) {\n const [pos, setPos] = React.useState(MIDDLE + (rollIn ? 0 : digit));\n const [moving, setMoving] = React.useState(false);\n const posRef = React.useRef(pos);\n const stripRef = React.useRef(null);\n\n React.useLayoutEffect(() => {\n const current = posRef.current;\n const showing = ((current % 10) + 10) % 10;\n if (showing === digit) return;\n if (reduced) {\n posRef.current = MIDDLE + digit;\n setMoving(false);\n setPos(MIDDLE + digit);\n return;\n }\n const up = trend > 0 || (trend === 0 && digit > showing);\n let target = up\n ? current + ((digit - showing + 10) % 10)\n : current - ((showing - digit + 10) % 10);\n // Values arriving faster than a roll (a progress percent) never let it re-centre, so before it runs off the strip,\n // jump the strip back by whole sets mid-roll (it looks identical) and roll on from there.\n if (target < 10 || target > SETS * 10 - 11) {\n const shift = Math.round((target - MIDDLE) / 10) * 10;\n const strip = stripRef.current;\n if (strip?.offsetHeight) {\n let visual = current;\n try {\n visual =\n -new DOMMatrixReadOnly(getComputedStyle(strip).transform).m42 /\n (strip.offsetHeight / (SETS * 10));\n } catch {}\n const transition = strip.style.transition;\n strip.style.transition = \"none\";\n strip.style.transform = `translateY(${(-(visual - shift) * 100) / (SETS * 10)}%)`;\n void strip.offsetHeight;\n strip.style.transition = transition;\n }\n target -= shift;\n }\n posRef.current = target;\n setMoving(true);\n setPos(target);\n }, [digit, trend, reduced]);\n\n // After a roll, quietly re-centre on the middle set so the next roll always has room.\n const settle = () => {\n const centred = MIDDLE + (((posRef.current % 10) + 10) % 10);\n posRef.current = centred;\n setMoving(false);\n setPos(centred);\n };\n\n return (\n \n {digit}\n \n {STRIP}\n \n \n );\n});\n\n/** A place that appeared after the first paint slides open; places that were there from the start just sit. */\nfunction Place({\n enter,\n children,\n}: {\n enter: boolean;\n children: React.ReactNode;\n}) {\n const [entering] = React.useState(enter);\n return (\n \n {children}\n \n );\n}\n\nexport function NumberRoll({\n value,\n format,\n locales,\n prefix = \"\",\n suffix = \"\",\n from,\n duration = 900,\n direction,\n className = \"\",\n ...props\n}: NumberRollProps) {\n const reduced = useReducedMotion();\n const [shown, setShown] = React.useState(from ?? value);\n const previous = React.useRef(shown);\n const mounted = React.useRef(false);\n\n // Roll from `from` to the real value once on screen (a frame later, so the start is painted).\n React.useEffect(() => {\n const frame = requestAnimationFrame(() => setShown(value));\n return () => cancelAnimationFrame(frame);\n }, [value]);\n\n React.useEffect(() => {\n mounted.current = true;\n }, []);\n\n const formatter = React.useMemo(\n () => new Intl.NumberFormat(locales, format),\n [locales, format && JSON.stringify(format)],\n );\n const text = `${prefix}${formatter.format(shown)}${suffix}`;\n const cols = React.useMemo(() => columns(text), [text]);\n const trend =\n direction === \"up\"\n ? 1\n : direction === \"down\"\n ? -1\n : Math.sign(shown - previous.current);\n\n // Places that disappear fold away instead of vanishing.\n const [leaving, setLeaving] = React.useState([]);\n const lastCols = React.useRef(cols);\n React.useLayoutEffect(() => {\n const gone = lastCols.current.filter(\n (c) => !cols.some((n) => n.key === c.key),\n );\n lastCols.current = cols;\n previous.current = shown;\n if (!gone.length || reduced) return;\n setLeaving(gone);\n const timer = window.setTimeout(() => setLeaving([]), 420);\n return () => window.clearTimeout(timer);\n }, [cols, shown, reduced]);\n\n return (\n \n {`${prefix}${formatter.format(value)}${suffix}`}\n \n {leaving.map((c) => (\n \n {c.char}\n \n ))}\n {cols.map((c) => (\n \n {c.digit === null ? (\n c.char\n ) : (\n \n )}\n \n ))}\n \n \n );\n}\n", "type": "registry:component" } ], "css": { "@keyframes ui-col-in": { "from": { "max-width": "0", "opacity": "0" }, "to": { "max-width": "1em", "opacity": "1" } }, "@keyframes ui-col-out": { "from": { "max-width": "1em", "opacity": "1" }, "to": { "max-width": "0", "opacity": "0" } } }, "meta": { "license": "MIT", "cavemio": { "component": "number-roll", "exportName": "NumberRoll", "usage": "import { NumberRoll } from \"@/components/number-roll\";\n\n\n", "accessibility": "The full formatted value is available as real text to screen readers. Decorative digit columns are hidden. Tabular figures keep the digits aligned; reduced motion disables digit rolling.", "previewNote": "Demo values are local; no network requests.", "documentation": { "useCases": [ { "title": "Pricing pages", "description": "Animate a price when the billing period or plan changes." }, { "title": "Live dashboards", "description": "Keep changing metrics readable as new data arrives." }, { "title": "Landing page stats", "description": "Roll a number from an initial value when the component mounts." }, { "title": "Countdowns and timers", "description": "Use a fixed downward direction for decreasing values." } ], "features": [ { "title": "Digits follow the value", "description": "Each column rolls in the direction the number moves." }, { "title": "Room for another digit", "description": "New places expand into the number and removed places fold away." }, { "title": "Formatting built in", "description": "Pass Intl.NumberFormat options for currency, percentages and compact values." }, { "title": "Real text underneath", "description": "Assistive technology and copy-and-paste receive the formatted value." } ], "states": [ { "title": "Rolling", "description": "Changed digits roll to their next value; unchanged places stay still." }, { "title": "Growing", "description": "Additional digit places open when the value grows." }, { "title": "Shrinking", "description": "Places no longer needed collapse from the number." }, { "title": "Initial count-up", "description": "Supply from to animate from a starting number after mount." } ], "props": [ { "name": "value", "type": "number", "description": "The number to display." }, { "name": "format", "type": "Intl.NumberFormatOptions", "description": "Currency, percent, decimals, compact notation or grouping." }, { "name": "locales", "type": "string | string[]", "description": "Locale used to format the number." }, { "name": "prefix / suffix", "type": "string", "description": "Text placed before or after the formatted number." }, { "name": "from", "type": "number", "description": "Optional starting value for the initial count-up." }, { "name": "duration", "type": "number · 900", "description": "Roll duration in milliseconds." }, { "name": "direction", "type": "\"up\" | \"down\"", "description": "Override the direction inferred from value changes." } ] }, "categories": [ "text" ] } }, "type": "registry:component" }