Gauge

Gauge builds a round dial from SVG parts that share one domain — track, arc, zones, ticks, needle, value text, and insets. Pass value, min, and max on the root; compose only the parts the reading needs. Wrap with GaugeControl when the dial should also adjust the value on a polar arc (single or dual thumb).

Reach for Gauge when the metaphor is polar: KPI rings, instrument chrome, nested arcs. Prefer Meter for a compact horizontal capacity bar, Slider for a linear interactive track, IconMeter for discrete icon-row scores, and LinearProgress for in-progress or indeterminate work. Part color is optional — omit it for theme defaults, or pass any valid CSS color (#hex, named colors, oklch(), var(--*), …); Gauge has no Meter-style variant.

Always name read-only dials with label (or aria-label), and always pass label on GaugeControl.

AnatomyCopy Anchor Link

Import the component and assemble its parts:

import {
  Gauge,
  GaugeArc,
  GaugeControl,
  GaugeDot,
  GaugeHub,
  GaugeInset,
  GaugeMarks,
  GaugeNeedle,
  GaugeStack,
  GaugeText,
  GaugeTickFill,
  GaugeTickLabels,
  GaugeTicks,
  GaugeTooltip,
  GaugeTrack,
  GaugeValue,
  GaugeZones,
} from '@viraui/react';

<GaugeControl>
  <Gauge>
    <GaugeInset />
    <GaugeTrack />
    <GaugeArc />
    <GaugeStack />
    <GaugeZones />
    <GaugeTicks />
    <GaugeTickFill />
    <GaugeMarks />
    <GaugeTickLabels />
    <GaugeText />
    <GaugeValue />
    <GaugeDot />
    <GaugeNeedle />
    <GaugeHub />
    <GaugeTooltip />
  </Gauge>
</GaugeControl>

When to useCopy Anchor Link

• Determinate readings on a round dial (rings, needles, zone bands, nested insets)
• Polar single or dual-thumb adjustment with GaugeControl

When not to useCopy Anchor Link

• Compact horizontal capacity the user only reads → Meter
• Discrete icon-row scores (stars, hearts, pips) → IconMeter
• Linear interactive range on a track → Slider
• In-progress or indeterminate task progress → LinearProgress

RelatedCopy Anchor Link

• Meter — read-only scalar on a horizontal track
• IconMeter — discrete filled / half / empty icon row
• Slider — linear thumb range input
• LinearProgress — task progress bars

Common examplesCopy Anchor Link

Simple dialCopy Anchor Link

Track, arc, and a large centered value are the baseline read-only dial. Add parts only when the reading needs them.

Progress ringCopy Anchor Link

A full-circle ring suits completion; a half-ring suits a single KPI. Stack both when the page shows completion and a headline metric together.

Zones and needleCopy Anchor Link

Zone bands plus a pointer needle read as instrument chrome. Keep tick density modest; let zoneCutoffs drive marks at band edges.

Dual rangeCopy Anchor Link

Pass a two-element value for a comfort band with dots at both ends. Pair with a single-thumb thermostat-style dial when the page needs both band and setpoint.

Nested insetCopy Anchor Link

GaugeInset nests child dials on the same polar plane — concentric activity rings, or a secondary fuel arc beside a primary needle.

Compass dialCopy Anchor Link

A full-circle 0–360 domain with compassLabel on the ticks reads as a heading bezel. Use kind="compass" for a north-marked needle, or kind="arrow" for a wind vane with speed in the hub gap.

Timer and clockCopy Anchor Link

Full-circle time dials share startAngle={180} / endAngle={540} (twelve at the top). A clock uses hour + minute needles with turns={12} on the minute hand and clockLabel on the hours; a timer is a 0–60 ring with a mono second readout; a chronograph adds a sweeping second hand plus a minute-register GaugeInset.

Value tooltipCopy Anchor Link

GaugeTooltip paints a small elevated bubble next to the dial — default content is an optional label over the formatted value and unit. With position="value" it sits outward from the reading on the arc (here near the end of the fill). Hover, press, or focus shows it; pass open to keep it up. In an iframe or docs sandbox, pass container to that document’s body so the portal stays with the dial.

Segment fillCopy Anchor Link

GaugeTickFill lights discrete ticks along the ring instead of a continuous arc — useful when the reading should feel stepped.

Interactive controlCopy Anchor Link

Wrap the dial in GaugeControl for polar adjustment. Keep Control angles aligned with the child Gauge; pass label on Control and hide decorative dial chrome from AT with aria-hidden when Control owns the name.

Part colorsCopy Anchor Link

Omit part color to keep theme defaults. When you need paint, pass any valid CSS color string on parts and zones[].color — hex, named colors, oklch(), or theme var(--*). Drive the live arc with zoneColor so the fill tracks the active band as the value moves.

Ask your agentCopy Anchor Link

Add a round gauge on this dashboard card for the main reading — track, arc, and a large centered value. Read-only, labeled for assistive tech.