Meter

When to use

Meter shows one value measured in a known range: storage used, a quota, a score, a fill level. The value can move either way; getting closer to or further from a limit is meaningful.

When not to use

• For the progress of a task: use Progress for work that starts and finishes (upload, install); Meter shows a measure, not progress.
• For an unknown wait: use Spinner or Skeleton when the duration is unknown.
• For several measures and trends: use Chart to compare or to show change over time.
• For a single number: use StatCard for a value and its change.

Anatomy

1. Label: what is measured; it names the meter.
2. Value: the formatted value opposite the label; hidden from screen readers, which read aria-valuetext instead.
3. Track (track): the whole range, in surface-sunken.
4. Fill (indicator): the bar up to the value, in a status colour.
5. Description: optional helper text.

Behaviour

• Meter is static: it does not change on hover and is not a tab stop.
• When the value changes, the fill scales to its new length over 150 ms; on first show it grows from zero. It never loops.
• A value outside the range is drawn at the nearest end; aria-valuenow is clamped to it.
• In right-to-left languages the fill grows from the right edge.
• tone="auto" finds the region with this rule: a value below low is low, above high is high, and anything between them (ends included) is middle. The region that holds optimum is good (success), its neighbour is a warning and the region at the far end is danger. When optimum is in the middle, both sides are warnings. A missing low is min, a missing high is max, and a missing optimum is the middle of the range. With none of the three the colour is brand.

Guidelines

Support colour with a word

auto also tells screen readers the region. If you pass a fixed tone, give the meaning in text too.

Quota used%92

x

DoFor a quota the best value is 0: thresholds set the colour and the word together.

Quota used%92

x

Don'tA fixed green at 92: the colour says good and carries no meaning.

Pick the format that fits the measure

Show the real unit; the percent of the range is not always the best result.

Storage32 GB

x

DoThe unit is shown: 32 GB.

Storage32

x

Don'tThe range is 0 to 50 but the value is a bare number.

Give context instead of removing the label

A label is always required. When the surrounding text already says it, use labelHidden; do not delete the label.

Score%70

x

DoThe label is visible; the meter has a clear name.

x

Don'tA bar without a label: what is measured is unknown.

Content

• Write the label as a noun phrase in sentence case: “Storage”, “Quota used”.
• Format the value with Intl; attach the unit to the value.
• Keep description to one sentence: when it was updated or what the limit is.
• When you write valueText, give a full phrase: “32 of 50 GB used”.

Related components

• StatCard: shows a single number with its change.
• Field: for the label and description pattern.
• Badge: shows a status as a label.