What it does
Gauge maps a value within a configurable range onto an SVG arc. Values outside that range are clamped so the graphic and accessible meter state remain aligned.
Radial and dial variants
Use the default radial variant for a complete 360-degree ring. Choose the dial variant for a rounded 270-degree arc with an open lower edge, which reads naturally for performance and capacity metrics.
Common use cases
- Dashboard KPIs such as capacity, utilization, and health scores.
- Storage, quota, and resource-consumption summaries.
- Performance, speed, and quality dials.
- Compact completion indicators where a linear bar does not fit.
Accessibility
The visible percentage is not the only source of meaning. Gauge exposes meter semantics, the numeric range, current value, a readable value string, and an accessible label on the root.
Next.js integration notes
Gauge is exported from its own client entry and has no Framer Motion dependency. Import it from @zentauri-ui/zentauri-components/ui/gauge in an App Router client subtree or render it through a server component boundary.
FAQ
How is Gauge different from Progress?
Gauge presents a determinate value as a circular ring or open dial and uses meter semantics. Progress remains the linear progress-bar primitive for task completion.
Can Gauge use a custom range and value format?
Yes. Set min and max for the range and use formatValue to render units, scores, storage values, or another readable string. The same text is exposed to assistive technology.
Is the Gauge component accessible?
The root uses role='meter' with minimum, maximum, current, and textual values. Supply a concise label that describes the measured quantity.