Skip to Content
BBRICKSv0.7.4
ShellOther

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

  1. Card (.kit-shell-usage, a labelled <section>): 20px × 22px padding, radius --r-lg, --card; bare drops the frame.
  2. Head (.kit-shell-usage-h): the <h2> label (display 15px) and the figure (<bdi dir="ltr">, 13px 700, tabular): "321 / 400", toned.
  3. Bar (role="meter", 8px, --track): the used part (raspberry; butter when warn; red when bad) and the reserved part (--rasp-soft).
  4. Notice (.kit-shell-usage-note, role="status"): a soft strip, butter when warn, raspberry-50 when bad.
  5. Stats (<dl>): soft tiles, auto-fit 110px+ (label 12px, value display 17px 800).

Variants

Tone (tone or derived)WhenLook
'ok'used / limit < warn (0.8)Raspberry bar, ink figure.
'warn'≥ 0.8Butter bar and figure, butter notice.
'bad'≥ bad (1, full) or overRed bar and figure, raspberry-50 notice.
PropLook
limit={null}Figure is used only; "No limit set" instead of a bar.
reservedLighter segment after used (invites holding seats), capped at the space left.
bareNo card: head and bar only.
statsTiles under the bar (Selected, Reserved, Available, Allowance).

States

StateHow
Defaultused 321, reserved 17, limit 400.
Near limit372 / 400 (warn) with notice.
Over limit412 / 400 (bad); bar full.
No limitlimit={null}.
Zero limitlimit={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 the AppShell stories' page and the shell gallery; fits Brand › Creators (seat limit) and PR › Brands (a brand's seats).

Guidelines

Do

  • Count invites waiting as reserved so the bar shows seats they hold.
  • Add a notice that says what to do at warn and bad.

Don't

  • Don't use it for money; use WalletHealthCard or ProgressRow.
  • 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 is role="meter" with aria-valuemin/max/now and aria-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.

  • 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.

On this page