Gauge

A circular visual for conveying a percentage.

Playground

Open Show controls to change the size and value, and to try the options.

Sizes

sm, md, lg and xl are 20, 32, 64 and 128px. The default is md.

import { Gauge } from "@smallest-inc/ui";

export default function GaugeSizes() {
  return (
    <div className="flex items-center gap-6">
      <Gauge size="sm" value={50} aria-label="Credits used" />
      <Gauge size="md" value={50} aria-label="Credits used" />
      <Gauge size="lg" value={50} aria-label="Credits used" />
      <Gauge size="xl" value={50} aria-label="Credits used" />
    </div>
  );
}

Show value

showValue prints the number in the center from md up. It never adds a unit; put units in the label beside it.

100

import { Gauge } from "@smallest-inc/ui";

export default function GaugeShowValue() {
  return (
    <div className="flex items-center gap-6">
      <Gauge showValue size="md" value={80} aria-label="Answer rate" />
      <Gauge showValue size="lg" value={80} aria-label="Answer rate" />
      <Gauge showValue size="xl" value={80} aria-label="Answer rate" />
      <Gauge showValue size="xl" value={100} aria-label="Answer rate" />
    </div>
  );
}

Custom colors

Pass a threshold map keyed by the value where each color starts. This one treats higher usage as worse.

100

import { Gauge } from "@smallest-inc/ui";

/** Higher usage is worse: each color starts at its key. */
const QUOTA_COLORS = {
  0: "var(--positive-solid)",
  50: "var(--brand-solid)",
  80: "var(--warning-solid)",
  95: "var(--danger-solid)",
};

export default function GaugeCustomColors() {
  return (
    <div className="flex items-center gap-6">
      {[12, 50, 80, 95, 100].map((value) => (
        <Gauge key={value} colors={QUOTA_COLORS} size="lg" value={value} showValue aria-label="Concurrency used" />
      ))}
    </div>
  );
}

Indeterminate

A static unknown state: a neutral track with a sparkle in the center. It hides the value and children.

import { Gauge } from "@smallest-inc/ui";

export default function GaugeIndeterminate() {
  return (
    <div className="flex items-center gap-6">
      <Gauge indeterminate size="md" value={0} aria-label="Usage not calculated yet" />
      <Gauge indeterminate size="lg" value={0} aria-label="Usage not calculated yet" />
      <Gauge indeterminate size="xl" value={0} aria-label="Usage not calculated yet" />
    </div>
  );
}

With icon

children renders in the center and wins over showValue. Icons scale with the gauge: 10, 16, 32 and 64px.

import { CheckIcon, Gauge } from "@smallest-inc/ui";

export default function GaugeWithIcon() {
  return (
    <div className="flex items-center gap-6">
      <Gauge size="md" value={100} colors={{ primary: "var(--positive-solid)" }} aria-label="Setup complete">
        <CheckIcon />
      </Gauge>
      <Gauge size="lg" value={100} colors={{ primary: "var(--positive-solid)" }} aria-label="Setup complete">
        <CheckIcon />
      </Gauge>
      <Gauge size="xl" value={100} colors={{ primary: "var(--positive-solid)" }} aria-label="Setup complete">
        <CheckIcon />
      </Gauge>
    </div>
  );
}

Best practices

When to use

Use for a 0–100 ratio against a fixed maximum where the comparison is the point — quota usage, hit rate, uptime, or billing-period consumption.
For determinate task progress with a known total (uploads, multi-step setup), use a progress bar or Stepper. For binary or enumerated state, use a status pill or Badge.

Behavior

Use arcPriority="equal" for true ratios so 50% reads as half. Keep the default primary arc when the filled portion is the story.
Threshold colors should match the same numeric breakpoints used elsewhere in the product. Do not invent gauge-only thresholds.
Use indeterminate for an unknown value. It is static (track + sparkle) — pair with nearby copy so it does not read as zero.

Content

Always pair the gauge with an adjacent label or Tooltip naming the metric. The gauge alone is not self-describing.
When showValue is on, render the number only — never inject a % or unit. Put units in the adjacent label.
children is reserved for an icon overlay, not units or captions.
showValue does nothing at sm; use md or larger when the number must show.

Accessibility

The component sets role="progressbar" with aria-valuemin, aria-valuemax, and aria-valuenow. Do not override those.
Tie an adjacent label with aria-labelledby, or pass aria-label naming the metric (“Minutes used”); an unlabelled progressbar is announced without context.
Do not encode thresholds with color alone; pair warning or danger tints with redundant text.

PreviousFrame NextHover Card