UsageMeter
How much of an allowance is used (the console's capacity meter, generalised): a labelled meter bar with the used part and an optional reserved part, the figure "used / limit", a tone from thresholds (ok → warn → bad), an optional notice and stat tiles. With no limit it says so instead of drawing a bar.
import { UsageMeter } from '@ergasti/bricks';Examples
Seat usage
Used, reserved and the limit as one bar; it turns warn and then bad as thresholds are crossed (80% and 100% by default); notice and stats add a sentence and a figures row.
Code
import { UsageMeter } from '@ergasti/bricks';
function Seats() {
return (
<div style={{ display: 'grid', gap: 16, maxWidth: 420 }}>
<UsageMeter label="Seat usage" used={120} limit={400} />
<UsageMeter label="Seat usage" used={321} reserved={17} limit={400} notice="You’re close to your creator limit. Ask TRNDR to raise it." stats={[{ label: 'Selected', value: 304 }, { label: 'Reserved', value: 17 }, { label: 'Available', value: 62 }]} />
<UsageMeter label="Seat usage" used={405} limit={400} />
<UsageMeter label="Seats used" used={321} limit={null} />
</div>
);
}Props
Prop
Type
Design guidance
How the BRICKS design system uses UsageMeter. Written in docs/content/components/UsageMeter.md; the props above are read from the code, which wins where the two disagree.
A labelled allowance meter: "Seat usage 321 / 400" with an 8px bar (used, plus an optional lighter reserved part), a tone that turns at thresholds, an optional notice and stat tiles; use it for seats, creator limits or any used-of-limit figure.
It generalises the console's capacity meter. The v3 Brand Home draws seat usage with a Gauge card (seatCard()); UsageMeter is the linear alternative for lists, settings and the sidebar (bare). With no limit it says "No limit set" instead of drawing a bar.
Anatomy
- Card (
.kit-shell-usage, a labelled<section>): 20px × 22px padding, radius--r-lg,--card;baredrops the frame. - Head (
.kit-shell-usage-h): the<h2>label (display 15px) and the figure (<bdi dir="ltr">, 13px 700, tabular): "321 / 400", toned. - Bar (
role="meter", 8px,--track): the used part (raspberry; butter when warn; red when bad) and the reserved part (--rasp-soft). - Notice (
.kit-shell-usage-note,role="status"): a soft strip, butter when warn, raspberry-50 when bad. - Stats (
<dl>): soft tiles, auto-fit 110px+ (label 12px, value display 17px 800).
Variants
Tone (tone or derived) | When | Look |
|---|---|---|
'ok' | used / limit < warn (0.8) | Raspberry bar, ink figure. |
'warn' | ≥ 0.8 | Butter bar and figure, butter notice. |
'bad' | ≥ bad (1, full) or over | Red bar and figure, raspberry-50 notice. |
| Prop | Look |
|---|---|
limit={null} | Figure is used only; "No limit set" instead of a bar. |
reserved | Lighter segment after used (invites holding seats), capped at the space left. |
bare | No card: head and bar only. |
stats | Tiles under the bar (Selected, Reserved, Available, Allowance). |
States
| State | How |
|---|---|
| Default | used 321, reserved 17, limit 400. |
| Near limit | 372 / 400 (warn) with notice. |
| Over limit | 412 / 400 (bad); bar full. |
| No limit | limit={null}. |
| Zero limit | limit={0}: bad when anything is used, empty bar. |
Types
UsageTone (tone): 'ok' | 'warn' | 'bad'.
Usage
<UsageMeter
label="Seat usage"
used={321}
reserved={17}
limit={400}
notice="You’re close to your creator limit. Ask TRNDR to raise it."
stats={[
{ label: 'Selected', value: 304 },
{ label: 'Reserved', value: 17 },
{ label: 'Available', value: 62 },
{ label: 'Allowance', value: 400 },
]}
/>import { UsageMeter } from '@ergasti/bricks';
// Above the creators list; the server decides the tone
export function SeatsBar({ seats }: { seats: { used: number; invited: number; limit: number | null; over: boolean } }) {
return <UsageMeter label="Seat usage" used={seats.used} reserved={seats.invited} limit={seats.limit} tone={seats.over ? 'bad' : undefined} />;
}Where it appears
- Not drawn in the v3 mocks (Brand Home's "Seat usage" card is a
Gauge). Shown at the top of theAppShellstories' page and the shell gallery; fits Brand › Creators (seat limit) and PR › Brands (a brand's seats).
Guidelines
Do
- Count invites waiting as
reservedso the bar shows seats they hold. - Add a
noticethat says what to do at warn and bad.
Don't
- Don't use it for money; use
WalletHealthCardorProgressRow. - Don't show it when there is nothing to limit;
limit={null}says "No limit set" for when the user expects one.
RTL and Arabic
- The bar fills from the right; the figure stays "321 / 400" (LTR).
- Arabic: "استخدام المقاعد", "مفيش حد متحدد", "321 من 400" spoken.
Tokens
--card, --line, --r-lg, --track, --rasp, --rasp-soft, --chart-butter, --butter, --butter-ink, --bad, --rasp-50, --soft, --ink-2, --ink-3, --font-family-display.
Accessibility
<section aria-labelledby>its label; the bar isrole="meter"witharia-valuemin/max/nowandaria-valuetext"321 of 400".- The notice is
role="status"; the figure is LTR-isolated. - Tone is never the only signal: the figure and notice say it.
Found in the source
- Roles in the markup:
meter,status. - ARIA attributes set:
aria-labelledby,aria-valuemin,aria-valuemax,aria-valuenow,aria-valuetext. - Its tests cover: “is a labelled region with a meter: value, max, words, and the used / reserved parts”.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
Gauge: Brand Home's round seat usage card.ProgressRow: progress toward a target in pips or a bar.Pips: a bare cell meter.
See also: useLanguage · EmptyView · ScreenErrorBoundary · useAppShell
Source
src/shell/UsageMeter.tsx (line 47) on GitHub.