# Meter
A short bar showing how full something is inside a known range, such as storage used, with an optional label and value.
Block: `smbk-meter`. Status: experimental. Figma: the Figma file, https://www.figma.com/community/file/1688324308358870630. Desktop and mobile: differ by presentation only.
## Options
| Axis | Values | Default | Meaning |
|---|---|---|---|
| `tone` | `series`, `success`, `warning`, `danger` | `series` | The fill: series is the chart color, for a level that is neither good nor bad; success, warning and danger say how the level stands. The page chooses it. |
## Markup
```html
```
## React
```tsx
import { Meter } from './design-system/components/meter/meter.js';
```
## Stylesheet
```css
/* smbk-meter — Meter. Figma "Meter" 7580:43 (Value × Tone), on "ProgressTrack" 4168:13602's track.
* How full something is inside a known range, such as storage used. Built on the progress bar: the
* root also carries smbk-progress and the parts carry its part classes, so the label row, the track
* (the subtle track color, pressed in, round ends) and the high contrast rules are the progress bar's.
* This stylesheet adds only what differs: a taller track and the fill's tones. The fill's width is set
* inline as a percentage by the wrapper; that is data, not a design value. */
.smbk-meter .smbk-progress__track {
height: var(--smbk-size-6);
}
/* ---- tone: the chart series color, or a feedback icon color ---- */
.smbk-meter--tone-series .smbk-progress__fill { background: var(--smbk-color-data-series); }
.smbk-meter--tone-success .smbk-progress__fill { background: var(--smbk-color-feedback-success-icon); }
.smbk-meter--tone-warning .smbk-progress__fill { background: var(--smbk-color-feedback-warning-icon); }
.smbk-meter--tone-danger .smbk-progress__fill { background: var(--smbk-color-feedback-danger-icon); }
/* ---- high contrast (forced colors) ---- */
/* The progress bar's rules draw the track and fill with the user's colors; the tones above would win
over them here, so they are put back. */
@media (forced-colors: active) {
.smbk-meter .smbk-progress__fill {
background: Highlight;
}
}
```
## Tokens it reads
```json
{
"size": {
"6": {
"$type": "dimension",
"$value": "6px",
"$description": "Raw size step, 6 px. Only for fixed sizes inside a component; semantic sizes (size/control, icon, mark) point here."
}
},
"color": {
"data": {
"series": {
"$type": "color",
"$value": "{{palette.light.series}}",
"$description": "The single series colour; the same as categorical 1, so one series and the first of many agree. Light blue/600, dark blue/400. Marks reach 3:1 on the plot background; never colour alone: direct labels, markers or patterns too."
}
},
"feedback": {
"success": {
"icon": {
"$type": "color",
"$value": "{{color.green.600}}",
"$description": "The success tone’s own icon (a check), so the tone is never shown by colour alone."
}
},
"warning": {
"icon": {
"$type": "color",
"$value": "{{color.orange.600}}",
"$description": "The warning tone’s own icon (a warning sign), so the tone is never shown by colour alone."
}
},
"danger": {
"icon": {
"$type": "color",
"$value": "{{color.red.600}}",
"$description": "The danger tone’s own icon (an alert sign), so the tone is never shown by colour alone."
}
}
}
}
}
```
## Purpose
Shows how full something is inside a known range: the storage used, the share of a monthly allowance spent, the seats taken. It answers "how much", not "how far along": for work that is getting done, use the progress bar.
## Anatomy
- The block, which also carries the progress bar's block class, as wide as its space.
- The header, an optional row with the label at the start and the value at the end, the progress bar's.
- The track, a short bar with round ends in the subtle track color, pressed in.
- The fill, laid over the track from the start edge as far as the value, in the tone's color.
The meter is built on the progress bar: its parts carry the progress bar's part classes, so the label row, the track and its round ends are the same, and only the meter's taller track and its tones are its own.
## When to use
- For a level inside a range that does not change while the reader watches: storage, quota, a budget.
- Several meters in a list, to compare levels with the same range.
## When not to use
- For the progress of an upload, an install or any task. Use the [progress bar](progress.md).
- For a value with no known end. Write the number.
- For a value over time. Use a chart.
## Behavior
The value is kept inside the range. The fill's length is the value's share of the range. The tone is chosen by the page: the chart color for a plain level, success, warning or danger for one that stands well or badly. The meter does not change its tone by itself.
The meter does not move on its own and takes no focus.
## Accessibility
### What it does for you
- The track is a meter to a screen reader, with its least and greatest values and the value now. A screen reader says it as a meter with the value.
- It takes no focus and no keys, and it does not move on its own.
- In high contrast mode the track is outlined and the fill drawn in the highlight color, as the progress bar's.
### What you must do
- Name it: its label, or an `aria-label`, or `aria-labelledby` pointing at words that name it.
- When a percentage is not what it measures, give the value in words with `aria-valuetext`, such as "62 of 100 GB". With the value shown, those words are what the row shows.
- Never let the tone be the only sign: say how the level stands in the label or the value, such as "almost full".
### How to test
- With a screen reader, it is read as a meter by its name, with its value, or with the words of `aria-valuetext` when given.
- Check that the level can be told without color: the label or the value says how it stands.
- With text at 200% and the page 320 pixels wide, the label row stays whole and the track fits its width.
- In a forced-color mode, the track is outlined and the fill is drawn in the highlight color.
## Usage rules
### Do
- Name what is measured in the label: "Storage", "Seats".
- Give the value in its own unit when the percentage hides it.
### Don't
- Use a meter to show a task getting done.
- Use the danger tone for a level that is not a problem.