Number flow
A number whose digits roll to their new value.
format takes the options of Intl.NumberFormat; prefix and suffix add text that does not roll. trend sets which way the digits turn: auto follows the change, up and down always turn one way, shortest takes the shorter way round. When the person prefers reduced motion, or with animated={false}, the new value is shown at once.
Counter
+2 days
"use client"
import { useState } from "react"
import { MinusIcon, PlusIcon } from "@keyline-icons/react"
import { Button } from "@/components/ui/button"
import { NumberFlow } from "@/components/ui/number-flow"
export default function NumberFlowCounter() {
const [days, setDays] = useState(2)
return (
<div className="flex items-center gap-4">
<Button size="icon" variant="outline" aria-label="Move the due date a day earlier" onClick={() => setDays(days - 1)}>
<MinusIcon />
</Button>
{/* The number is not a live region by itself: `aria-live` has a change read out. */}
<span aria-live="polite" className="min-w-24 text-center text-2xl">
<NumberFlow
value={days}
format={{ signDisplay: "exceptZero" }}
suffix={Math.abs(days) === 1 ? " day" : " days"}
/>
</span>
<Button size="icon" variant="outline" aria-label="Move the due date a day later" onClick={() => setDays(days + 1)}>
<PlusIcon />
</Button>
</div>
)
}
Formats
- Invoiced
- €184,200
- Growth
- +8.2%
- Visits
- 96K
- Response
- ~240 ms
"use client"
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { NumberFlow } from "@/components/ui/number-flow"
const quarters = [
{ name: "Q2 2026", invoiced: 184200, growth: 0.082, visits: 96400, response: 240 },
{ name: "Q3 2026", invoiced: 213750, growth: 0.16, visits: 128900, response: 185 },
{ name: "Q4 2026", invoiced: 197300, growth: -0.077, visits: 1204000, response: 1320 },
]
export default function NumberFlowFormats() {
const [index, setIndex] = useState(0)
const quarter = quarters[index % quarters.length]
if (!quarter) return null
return (
<div className="flex flex-col items-center gap-6">
<dl className="grid grid-cols-2 gap-x-8 gap-y-4 text-center sm:grid-cols-4">
<div>
<dt className="text-sm text-muted-foreground">Invoiced</dt>
<dd className="text-xl">
<NumberFlow
value={quarter.invoiced}
format={{ style: "currency", currency: "EUR", maximumFractionDigits: 0 }}
/>
</dd>
</div>
<div>
<dt className="text-sm text-muted-foreground">Growth</dt>
<dd className="text-xl">
<NumberFlow
value={quarter.growth}
format={{ style: "percent", maximumFractionDigits: 1, signDisplay: "exceptZero" }}
/>
</dd>
</div>
<div>
<dt className="text-sm text-muted-foreground">Visits</dt>
<dd className="text-xl">
<NumberFlow value={quarter.visits} format={{ notation: "compact" }} />
</dd>
</div>
<div>
<dt className="text-sm text-muted-foreground">Response</dt>
<dd className="text-xl">
<NumberFlow value={quarter.response} prefix="~" suffix=" ms" />
</dd>
</div>
</dl>
<Button variant="outline" onClick={() => setIndex(index + 1)}>
{quarter.name}: show the next quarter
</Button>
</div>
)
}
Rolling direction
- auto
- 27
- up
- 27
- down
- 27
- shortest
- 27
- still
- 27
"use client"
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { NumberFlow } from "@/components/ui/number-flow"
const values = [27, 42, 15, 38]
const trends = ["auto", "up", "down", "shortest"] as const
export default function NumberFlowRollingDirection() {
const [index, setIndex] = useState(0)
const value = values[index % values.length] ?? 0
return (
<div className="flex flex-col items-center gap-6">
<dl className="grid grid-cols-3 gap-x-6 gap-y-4 text-center sm:grid-cols-5">
{trends.map((trend) => (
<div key={trend}>
<dt className="text-sm text-muted-foreground">{trend}</dt>
<dd className="text-xl">
<NumberFlow value={value} trend={trend} />
</dd>
</div>
))}
<div>
<dt className="text-sm text-muted-foreground">still</dt>
<dd className="text-xl">
<NumberFlow value={value} animated={false} />
</dd>
</div>
</dl>
<Button variant="outline" onClick={() => setIndex(index + 1)}>
Change the value
</Button>
</div>
)
}
Installation
npx shadcn@latest add @khaeli/number-flowbunx --bun shadcn@latest add @khaeli/number-flowInstall @khaeli/foundation first: this item's styling lives in its tokens and [data-slot] rules.
Installs with
- Registry items
Accessible name
- The rolling digits are hidden from assistive technology. A visually hidden copy holds the whole formatted value with its prefix and suffix, so the number is read as written: +2 days.
- A change is not read out by itself. Put the number in an
aria-live="polite"element when a person needs to hear the new value.
Registry JSON
The item as the shadcn CLI reads it, with every file it ships: https://ui.khaeli.com/r/number-flow.json