Gauge
A reading on a dial: an arc that fills as far as the value has come.
On this page
A gauge is a reading on a dial: two thirds of a ring, open at the foot, that fills with ink as far as the value has come. The figure stands in the middle and one word under it, between the two ends of the arc. It is an element with role="meter", so the reading is written for people and the stylesheet draws it. There is no script and no SVG.
Gauge
<div class="card max-w(480) mx-auto"> <div class="flex flex-wrap justify-around gap-md"> <div class="gauge" role="meter" aria-label="CPU" aria-valuenow="38" style="--gauge-value: 38"> <span class="gauge-value">38%</span> <span class="gauge-label">CPU</span> </div> <div class="gauge" role="meter" aria-label="Memory" aria-valuenow="72" style="--gauge-value: 72"> <span class="gauge-value">72%</span> <span class="gauge-label">Memory</span> </div> <div class="gauge" role="meter" aria-label="Disk" aria-valuenow="91" style="--gauge-value: 91"> <span class="gauge-value">91%</span> <span class="gauge-label">Disk</span> </div> </div></div>#How the arc gets its length
The reading is aria-valuenow, between aria-valuemin and aria-valuemax, or 0 and 100 when they are left out. Where the browser supports typed attr(), the gauge reads those attributes itself, so the number is written once. Elsewhere it reads --gauge-value, and --gauge-min and --gauge-max for another range: until typed attr() is in every engine, write both, as the examples here do.
The track and the fill each end in a round cap, and the fill eases to a new reading. An empty gauge is an empty track: the caps have no size at nothing.
A range of its own
<div class="gauge" role="meter" aria-label="Engine speed" aria-valuenow="4200" aria-valuemin="0" aria-valuemax="8000" style="--gauge-value: 4200; --gauge-max: 8000"> <span class="gauge-value">4,200</span> <span class="gauge-label">rpm</span></div><div class="gauge" role="meter" aria-label="Rating" aria-valuenow="4.6" aria-valuemin="1" aria-valuemax="5" style="--gauge-value: 4.6; --gauge-min: 1; --gauge-max: 5"> <span class="gauge-value">4.6</span> <span class="gauge-label">of 5</span></div><div class="gauge" role="meter" aria-label="Queue" aria-valuenow="0" style="--gauge-value: 0"> <span class="gauge-value">0</span> <span class="gauge-label">Queued</span></div>#Sizes
A gauge is 120px across. gauge-sm is 88px, for a tile in a dense dashboard, and gauge-lg is 160px, for the one reading a view is about. The stroke is a fifteenth of the width and the figure scales with it. Without a gauge-label, the figure stands at the middle of the dial.
Sizes
<div class="gauge gauge-sm" role="meter" aria-label="Battery" aria-valuenow="64" style="--gauge-value: 64"> <span class="gauge-value">64%</span> <span class="gauge-label">Battery</span></div><div class="gauge" role="meter" aria-label="Battery" aria-valuenow="64" style="--gauge-value: 64"> <span class="gauge-value">64%</span> <span class="gauge-label">Battery</span></div><div class="gauge gauge-lg" role="meter" aria-label="Battery" aria-valuenow="64" style="--gauge-value: 64"> <span class="gauge-value">64%</span></div>#A reading that is a status
The fill is ink. When the reading itself is a warning, set --gauge-color to a status color and say so in words: a hue never carries the meaning alone. The track is the same color stepped back, so it follows.
Status
<div class="gauge" role="meter" aria-label="Storage" aria-valuenow="84" aria-valuetext="84%, nearly full" style="--gauge-value: 84; --gauge-color: var(--color-warning)"> <span class="gauge-value">84%</span> <span class="gauge-label">Nearly full</span></div><div class="gauge" role="meter" aria-label="Error budget" aria-valuenow="97" aria-valuetext="97% spent, over budget soon" style="--gauge-value: 97; --gauge-color: var(--color-danger)"> <span class="gauge-value">97%</span> <span class="gauge-label">Spent</span></div>#Gauge, meter or progress
A gauge and a meter both show a measurement within a range. Choose the gauge when the figure is the point and has room of its own, as on a dashboard; choose the meter for a line in a form or a row of a table. Progress is for a task that completes, and its ring closes; a gauge's arc never does.
#Accessibility
- Give the element
role="meter", an accessible name witharia-labeloraria-labelledby, and the reading inaria-valuenow. Addaria-valueminandaria-valuemaxwhen the range is not 0 to 100. - Write the reading again as the text of
gauge-value, with its unit. When the number needs words to be understood, addaria-valuetext. - The arc is drawn by the stylesheet and is not announced. In forced colors the fill takes the system highlight and the track the system's grey.
#Classes
| Class | Description |
|---|---|
gauge | The dial, 120px across, on an element with role="meter", an accessible name and the reading in aria-valuenow: two thirds of a ring, open at the foot, filled with ink as far as the reading |
gauge-sm | An 88px dial; the default is 120px. With gauge |
gauge-lg | A 160px dial; the default is 120px. With gauge |
gauge-value | The reading as text, in large tabular figures at the middle of the dial |
gauge-label | One quiet word under the figure, between the two ends of the arc; without it the figure stands at the middle |
#Custom properties
| Property | Default | Description |
|---|---|---|
--gauge-value | The reading. It comes from aria-valuenow where typed attr() is supported; set it by hand elsewhere | |
--gauge-min | 0 | The foot of the range. It comes from aria-valuemin where typed attr() is supported |
--gauge-max | 100 | The top of the range. It comes from aria-valuemax where typed attr() is supported |
--gauge-size | 7.5rem | The dial's diameter |
--gauge-width | calc(var(--gauge-size) / 15) | Thickness of the arc |
--gauge-color | var(--color-surface-inverse) | The ink of the fill; the track is the same color stepped back. Set a status color when the reading is one, and say so in words |