Skip to Content
BBRICKSv0.7.4
KitCharts

Gauge

Semi-circle gauge: segments laid end to end, clamped to max; one image to AT, the legend as text.

import { Gauge } from '@ergasti/bricks';

Examples

Seat usage

A half-ring split into segments; max is the full scale and center is what sits in the middle.

Code
import { Button, Card, Gauge } from '@ergasti/bricks';

function Seats() {
  return (
    <div style={{ maxWidth: 420 }}>
      <Card>
        <Card.Header title="Seat usage" sub="How many creators your plan lets you have" actions={<Button size="sm">Raise limit?</Button>} />
        <Card.Body>
          <Gauge
            label="Seat usage"
            max={400}
            center={<><b>321<span className="kit-muted" style={{ fontSize: 16 }}> / 400</span></b><span className="kit-muted">seats used</span></>}
            segments={[{ value: 304, label: 'Selected', tone: 'rasp' }, { value: 17, label: 'Reserved', tone: 'rasp-soft' }, { value: 79, label: 'Remaining', tone: 'track' }]}
          />
        </Card.Body>
      </Card>
    </div>
  );
}

Value and caption

Pass value and the gauge draws "321 / 400" itself: the value big, " / max" small and muted, kept left-to-right in Arabic; caption is the small line under it. A free center is still there for anything else.

Code
import { Card, Gauge } from '@ergasti/bricks';

function ValueAndCaption() {
  return (
    <div style={{ maxWidth: 420 }}>
      <Card>
        <Card.Header title="Seat usage" />
        <Card.Body>
          <Gauge
            label="Seat usage"
            max={400}
            value={321}
            caption="seats used"
            segments={[{ value: 304, label: 'Selected', tone: 'rasp' }, { value: 17, label: 'Reserved', tone: 'rasp-soft' }, { value: 79, label: 'Remaining', tone: 'track' }]}
          />
        </Card.Body>
      </Card>
    </div>
  );
}

Props

Prop

Type

Design guidance

How the BRICKS design system uses Gauge. Written in docs/content/components/Gauge.md; the props above are read from the code, which wins where the two disagree.

A semi-circle gauge that lays segments end to end against a maximum, with a big "value / max" in the middle and a legend below; use it for capacity such as seat usage.

Gauge is the mock's seatCard() half-donut on Brand › Home: a 220 × 120 SVG arc (radius 90, 18px round-capped stroke) over a grey track, one coloured arc per segment, clamped so the total never passes max. The centre shows the headline number ("321 / 400", "seats used") and a centred legend lists each segment with its count. Assistive tech gets one image whose name lists every segment.

Anatomy

  1. Track: the full arc in --track.
  2. Segment arcs: one per segment with value > 0, laid end to end from the left, in the segment's tone; a segment with tone: 'track' is not drawn (it is the remaining space).
  3. Centre (.kit-gauge-v): value in Jakarta 30/800 with " / max" muted 16/700, and caption muted 12px under it; or the free center node.
  4. Legend (ul.kit-legend--center): a 9px swatch, legend ?? label, and the value, per segment.

Variants

Segment tone (ChartTone):

ToneColourUse
'rasp'--raspThe main quantity ("Selected")
'rasp-soft'--rasp-softA held or pending share ("Reserved")
'track'--track (not drawn on the arc)What is left ("Remaining"): legend only
'butter'--chart-butterExtra category
'lime'--chart-limeExtra category
'sky'--sky-inkExtra category
'ink'--inkExtra category

Centre: value (+ caption) for the standard "321 / 400"; center for anything else.

States

StateTriggerLook
Defaultsegments below maxArcs cover part of the track
Fullsegments sum ≥ maxArc closes the semicircle; overflow is clamped
Emptyall coloured segments 0Only the grey track
No maxmax <= 0No arcs drawn (avoids division by zero)
Negative valuesegment value < 0Treated as 0 on the arc; the legend still prints the raw value

Types

GaugeSegment.legend replaces the label in the legend only (a Term with its tooltip).

GaugeSegment (segments): { value: number; label: string; tone: ChartTone; legend?: ReactNode }, in arc order. label is also the React key: keep it unique.

Usage

The Home seat card, with terms in the legend:

<Card>
  <Card.Header title="Seat usage" sub="How many creators your plan lets you have"
    actions={<Button size="sm">Raise limit?</Button>} />
  <Gauge label="Seat usage" max={400} value={321} caption="seats used"
    segments={[
      { value: 304, label: 'Selected', tone: 'rasp', legend: <Term tip="Creators in your program now. Each uses a seat.">Selected</Term> },
      { value: 17, label: 'Reserved', tone: 'rasp-soft', legend: <Term tip="Seats held for invites still waiting for a reply">Reserved</Term> },
      { value: 79, label: 'Remaining', tone: 'track', legend: <Term tip="Seats you can still fill">Remaining</Term> },
    ]} />
</Card>

A custom centre:

<Gauge label="Gift stock" max={120} center={<b>All claimed</b>}
  segments={[{ value: 120, label: 'Claimed', tone: 'lime' }]} />

Where it appears

  • Brand › Home › Seat usage card (with "Raise limit?" in the header).
  • Screen: Home.

Guidelines

Do

  • Make the segments add up to max, ending with a 'track' "Remaining" segment so the legend explains the grey part.
  • Use value + caption rather than hand-building the centre: it gets the mock's type and LTR digits.
  • Keep 2 to 4 segments.

Don't

  • Don't give two segments the same label (it is the key and part of the accessible name).
  • Don't use it for a trend or a share of revenue: use StackBar.
  • Don't squeeze it below 220px wide; the SVG is fixed at 220px.

RTL and Arabic

  • The arc does not mirror; it fills left to right in both languages.
  • "321 / 400" is dir="ltr" so the order stays value-first in Arabic.
  • The legend follows the page direction (swatch at the inline start).

Tokens

--track, --rasp, --rasp-soft, --chart-butter, --chart-lime, --sky-ink, --ink (segments), --font-family-display (value), --ink-3 (max, caption), --ink-2 (legend text).

Accessibility

  • The arc and centre are one role="img" with aria-label="{label}: Selected 304, Reserved 17, Remaining 79"; the SVG itself is aria-hidden.
  • The legend is a real list and stays readable; a Term in legend keeps its own focusable tooltip.
  • Colour is never the only cue: each swatch sits next to its label and number.

Found in the source

  • Roles in the markup: img.
  • ARIA attributes set: aria-label, aria-hidden.

Read from the component's source and tests. See Accessibility for the patterns the library follows.

  • StackBar: the same idea as a straight bar (commission status, wallet held/free).
  • Legend: the legend on its own.
  • UsageMeter / UsageBar: linear usage against a limit.

See also: Card · Button · AreaTrend · BarChart · HBars

Source

src/kit/patterns/Gauge.tsx (line 58) on GitHub.

On this page