Geist Design System

Gauge

A circular visual for conveying a percentage.

Default

Label

Default color scale

Custom color range

Custom secondary color

Arc priority

When using the gauge to display a ratio, use the equal arc priority to make both arcs are equally sized.

Indeterminate

Best Practices

When to use

  • A 0–100 ratio against a fixed maximum where the comparison is the point, like quota usage, build cache hit rate, uptime, or billing-period consumption.
  • For determinate task progress with a known total (uploads, multi-step setup), use Progress.
  • For binary or enumerated state, use Status Dot for deployments or Badge for everything else.

Behavior

  • Use arc="equal" for true ratios so 50% reads as exactly half. Use the default primary arc for single-percentage usage where the filled portion is the story.
  • Threshold colors should match the same numeric breakpoints used elsewhere in the product (>=80% warning, >=95% error). Don’t invent gauge-only thresholds.
  • Pair indeterminate with explanatory copy nearby (Calculating usage…) so the user knows the value is loading, not zero.

Content

  • Always pair the gauge with an adjacent label or Tooltip naming what the number represents (Build Cache Hit Rate). The gauge alone is not self-describing.
  • Don’t put units inside children; the label carries the unit (Uptime · 99.97%). children is reserved for an icon overlay.
  • When showValue is on, the rendered number is the value only. Never inject a % or unit string into the prop.

Accessibility

  • The component sets role="progressbar" with aria-valuemin, aria-valuemax, and aria-valuenow. Don’t override those.
  • The adjacent label is the gauge’s accessible name. Tie it with aria-labelledby on the gauge wrapper so screen readers read “Uptime, 99 percent.”
  • Don’t use color to encode the threshold without redundant text; pair the warning tint with copy below or in the Tooltip.