Meter
How far along or how full something is, from 0 to 100, as a bar, a ring or a half ring, with optional red, amber and green zones.
Master
Switch shape, size and thresholds; turn on reference lines and the value. Value moves it between the zones.
Usage
Use Meter for task completion (uploads, setup) and for measures against a range (storage used, budget spent, health scores). It is one component: pass value from 0 to 100 and a label that names it; value indeterminate slides a segment along the bar while the amount done is not known. shape picks a bar, a circle or a semicircle gauge (a bowl that fills left to right); size sets the bar thickness or the ring width. thresholds splits the range into thirds, low red, middle amber, high green: bar colors the value by its zone, plotArea colors the track, all shows the three bands. referenceLines marks the zone edges. showValue writes the percent after the bar or inside the ring, and datatip puts a short note in a tip at the end of the value. See contracts/meter.json for the full contract.
Do's
- Task completion with a known percent: uploads, imports, onboarding.
- A measure against a range, like storage, budget or a score, where red, amber and green zones help people judge it.
- A color the screen decides, like a usage limit going amber and red: set intent.
Don'ts
- Do not use it for a short wait of unknown length in the spot that is loading. Show a Spinner. indeterminate is for a bar that sits with the work, like a loading Toast, or that will get a value later.
- Do not use indeterminate with circle or semicircle; it is bar only.
- Do not draw bars or rings from divs or SVG. Use Meter.
- Do not add a MeterLabel, MeterCircle or ProgressCircle. Pick shape.
- Do not use intent and thresholds bar together. intent wins; pick one.
- Do not rely on the zone colors alone; say what the value means in the label, showValue or datatip.
- For screens that still use the older 20-tall bar, use ProgressBar.
- Do not use raw hex.
<Meter label="Budget spent" shape="bar" size="md" thresholds="none" showValue />