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.

API requests
74%742k / 1M258k left
Props
Value742000
Max1000000
Color
theme
Thickness6
Swell1.00
Cell size2
Warn at0.75
Danger at0.90

Installation

pnpm dlx shadcn@latest add @breeze/usage-bar

Usage

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

API requests
74%742k / 1M258k left
StorageNear limit
76%38.2 GB / 50 GB11.8 GB left
Team seats
70%7 / 103 left
Build minutesAlmost full
92%1,840 / 2,000160 left

Props

PropTypeDefaultDescription
labelReactNodeName of the meter
iconReactNodeShown before the label
valuenumberAmount used
maxnumberThe limit
unitstring""Text after numbers, e.g. " GB"
format(n: number) => stringcompact or groupedCustom number formatting
colorstring"var(--brand)"Fill colour while usage is fine
warnColorstring"#f5b400"Fill colour from warnAt
dangerColorstring"#ef4444"Fill colour from dangerAt
warnAtnumber0.750 to 1, where it turns amber
dangerAtnumber0.90 to 1, where it turns red
thicknessnumber6Body thickness in px
swellnumber1How much the head swells while it moves, 0 to 2
cellSizenumber2Dither cell size in px
animatebooleantrueSpring to the value, swelling on the way
hideStatusbooleanfalseHide the status pill and the "left" figure

The meter has role="meter" with the value, limit and percentage, so screen readers announce it.