KQ-591 · BALANCE/ROLL

Balance Roll

A balance whose digit columns roll to the new figure on glide, in a cascade that starts at the units and ripples left the way an odometer's small wheels stop first. Each column is one eleven-face strip — the ten digits and a bullet — so pressing the figure rolls it to dots instead of swapping in a placeholder, and the separators only fade, which keeps the layout still. A change slides a delta chip in beside the figure on snap and takes it away on the exit ease; the press is an aria-pressed button whose name carries the amount, so Enter and Space mask it and no reader wades through the columns.

KQ-591 · BALANCE/ROLL

Available balance

Waylight Pay · Everyday

Balance $8,412.60

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/balance-roll

Props

value: number; default —; The balance in major units. Changing it rolls the digits and raises the delta chip.
label: string; default —; What the figure is; labels the readout for assistive technology.
format: (value: number) => string; default Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }); Turns an amount into its printed string. The default pins an explicit locale so server and client agree.
masked / defaultMasked: boolean; default false; Controlled or initial mask state; masked rolls every digit on to a bullet.
onMaskedChange: (masked: boolean) => void; default —; Fires from the press that toggled the mask.
onValueSettle: (value: number, delta: number) => void; default —; Fires once per settled change, from the effect that observed it.
deltaHoldMs: number; default 2600; Milliseconds the delta chip holds before it fades; 0 keeps it up.
caption: React.ReactNode; default —; A quiet line under the figure — the account the balance belongs to.

Prop	Type	Default	Description
value	number	—	The balance in major units. Changing it rolls the digits and raises the delta chip.
label	string	—	What the figure is; labels the readout for assistive technology.
format	(value: number) => string	Intl.NumberFormat("en-US", { style: "currency", currency: "USD" })	Turns an amount into its printed string. The default pins an explicit locale so server and client agree.
masked / defaultMasked	boolean	false	Controlled or initial mask state; masked rolls every digit on to a bullet.
onMaskedChange	(masked: boolean) => void	—	Fires from the press that toggled the mask.
onValueSettle	(value: number, delta: number) => void	—	Fires once per settled change, from the effect that observed it.
deltaHoldMs	number	2600	Milliseconds the delta chip holds before it fades; 0 keeps it up.
caption	React.ReactNode	—	A quiet line under the figure — the account the balance belongs to.