Home/ Cookbook/ Charts/ Gauge

Semicircle gauge

A half-donut arc encoding one bounded score (0–100). Beloved by execs, divisive among designers — and unavoidable when leadership says "give me a dial".

Charts · 18 of 20 1 primitive · Chart.Gauge ~10 min React · @corelithzw/react

Overview

A 180° arc with a coloured fill from one end and a big centred number. The visual metaphor everyone already knows.

Gauges trade information density for emotional clarity. They take more pixels than a bullet or a progress ring to convey the same fact, but they read as "dashboard" the moment they land on screen — that aesthetic is sometimes the whole point. Use them on landing screens, exec dashboards, and customer-facing reports where a familiar shape outweighs a more efficient one.

Reach for it when the metric is bounded 0–100 (score, percentage, NPS), and the chart will be looked at by people who don't read charts every day. Skip it for analytical screens — a bullet chart shows the same data plus targets and bands in less space. Never stack ten gauges in a row; if you would, switch to bullets.

The opinion: a gauge needs the number printed in the middle. If the user has to read the arc to know the value, the chart failed. The arc colours the verdict; the number carries the precision.

The chart

Customer satisfaction score at 82 of 100 — sits in the "good" band, marked by colour and label.

CSAT score Semi-circle gauge showing 82 of 100. Bands: 0-50 poor, 50-80 average, 80-100 good. Score sits in the good band. 82 of 100 · CSAT good 0 100

Required pieces

PrimitiveChart.Gauge BlockStat hero
Roadmap: Chart.Gauge in v0.2 supports bands, target ticks, and animated reveal. For v0.1-alpha, the inline SVG above is the entire footprint.

React snippet

Pass value, max, and optional bands; the band the value falls in becomes the auto-label.

82 of 100 · CSAT
Chart.Gauge@corelithzw/react

Customising

Full-circle gauge

Replace the semicircle with a 270° arc when the dashboard tile is square; the bigger arc reads as "more bandwidth used".

<Chart.Gauge
  value={82}
  max={100}
  arc="three-quarter"
  startAngle={-225}
  endAngle={45}
/>

Multi-gauge in a card

Three small gauges in a row for tri-metric dashboards. Drop the band labels — read each as a tile, not a feature.

{metrics.map(m => (
  <Chart.Gauge
    key={m.id}
    value={m.value}
    max={m.max}
    width={140}
  />
))}

Gauge with delta

Add a "+5 vs. last month" subtitle so the gauge stops looking like a static dial.

<Chart.Gauge
  value={82}
  max={100}
  sublabel="+5 vs. last month"
  sublabelTone="success"
/>

In context

Inside a stat hero card on the exec dashboard. The gauge sits next to a short copy explanation and a comparison bullet of last quarter.

82 of 100
Customer satisfaction
Good · 82
Up 5 points since June. Target for the year is 85 — on track if November holds.

Accessibility

Gauges look approachable but pack a lot of meaning into an arc. Lead with the number and the band, both as text.

  • One role="img" per gauge. Inside, <title> names the metric; <desc> spells out the value, scale, and band.
  • The number is real text. Centred <text> elements, not images — screen readers can read "82" without needing an aria-label.
  • Band name is text-redundant. "Good" appears both as a coloured pill and as the band label in the aria-label.
  • Min/max labels visible. "0" and "100" at the arc's endpoints save users from inferring the scale.
  • Target tick has a non-colour cue. The target is a thicker ink-coloured tick plus an aria-label "target 80" inside the desc.
  • No motion in reduced motion. The arc draw-in honours prefers-reduced-motion: reduce and shows the final state immediately.