Usage Bar
A usage meter drawn as a dithered liquid along a thin rail. Its head swells as it surges forward, and it turns amber, then red, as you near the limit.
Installation
pnpm dlx shadcn@latest add @breeze/usage-barUsage
import { UsageBar } from "@/components/breeze/usage-bar"<UsageBar label="API requests" value={742_000} max={1_000_000} />Numbers format themselves: big ones go compact (742k / 1M), small ones stay grouped (1,840 / 2,000). Add a unit for things like storage, or pass your own format.
<UsageBar label="Storage" value={38.2} max={50} unit=" GB" />Anatomy
- Readout: a small tracked label, the percentage large, the raw figures in mono, and what's left on the right.
- Rail: a hairline with quarter ticks. Small notches mark the warn and danger points, in their colours, so you can see the limit coming.
- Fill: a dithered liquid in the same ordered-dither texture as Curtains and Waves. It's slim at the start and thickens and brightens toward a rounded head.
Motion
The head springs to the value when the meter appears and whenever the value changes. While it surges forward, the head swells with its speed, then relaxes into a soft nose once it stops; going back down it just slides. swell sets how much it swells, and animate={false} (or reduced motion) makes it jump straight to the value.
Status
The fill uses color while usage is fine, warnColor from warnAt (75% by default) and dangerColor from dangerAt (90%). Past each point a small pill says Near limit or Almost full.
Examples
Plan usage
import { ArrowLeftRight, Database, Timer, Users } from "lucide-react"
import { UsageBar } from "@/components/breeze/usage-bar"
export function PlanUsage() {
return (
<div className="grid gap-x-12 gap-y-8 sm:grid-cols-2">
<UsageBar
icon={<ArrowLeftRight className="size-3.5 text-blue-500" />}
label="API requests"
value={742_000}
max={1_000_000}
color="#3b82f6"
/>
<UsageBar
icon={<Database className="size-3.5 text-cyan-500" />}
label="Storage"
value={38.2}
max={50}
unit=" GB"
color="#06b6d4"
/>
<UsageBar
icon={<Users className="size-3.5 text-violet-500" />}
label="Team seats"
value={7}
max={10}
color="#8b5cf6"
/>
<UsageBar
icon={<Timer className="size-3.5 text-orange-500" />}
label="Build minutes"
value={1840}
max={2000}
color="#f97316"
/>
</div>
)
}Props
| Prop | Type | Default | Description |
|---|---|---|---|
label | ReactNode | Name of the meter | |
icon | ReactNode | Shown before the label | |
value | number | Amount used | |
max | number | The limit | |
unit | string | "" | Text after numbers, e.g. " GB" |
format | (n: number) => string | compact or grouped | Custom number formatting |
color | string | "var(--brand)" | Fill colour while usage is fine |
warnColor | string | "#f5b400" | Fill colour from warnAt |
dangerColor | string | "#ef4444" | Fill colour from dangerAt |
warnAt | number | 0.75 | 0 to 1, where it turns amber |
dangerAt | number | 0.9 | 0 to 1, where it turns red |
thickness | number | 6 | Body thickness in px |
swell | number | 1 | How much the head swells while it moves, 0 to 2 |
cellSize | number | 2 | Dither cell size in px |
animate | boolean | true | Spring to the value, swelling on the way |
hideStatus | boolean | false | Hide the status pill and the "left" figure |
The meter has role="meter" with the value, limit and percentage, so screen readers announce it.