Skip to contentSkip to navigationSkip to topbar
Figma
Star

Meter

Meter is a visual representation of a numerical value within a known range.

Version 1.0.3
Github
Component preview theme
const DefaultMeterExample = () => {
const meterId = useUID()
const helpTextId = useUID()
return (
<Box maxWidth="size30">
<MeterLabel htmlFor={meterId} valueLabel="89%">Emails delivered</MeterLabel>
<Meter value={89} id={meterId} />
<HelpText id={helpTextId}>Showing successful deliveries of June email campaign.</HelpText>
</Box>
);
};
render(
<DefaultMeterExample />
)

Guidelines

Guidelines page anchor

About Meter

About Meter page anchor

A Meter is a visual representation to indicate how full something is.

A Meter represents a bucket that can be empty, full, or somewhere in between. Use a Meter when you need to show capacity. For example, use a Meter to show how much data is being used or how many emails were sent successfully.

A Progress Bar represents only task completion, like a file upload or filling out a form. If you’re not displaying progress on a particular task, use a Meter.

A label is required when using Meter. Use one of these options:

  • Visible label using MeterLabel, with htmlFor set equal to the id of the Meter (preferred)
  • Visible label that's associated to the Meter with aria-labelledby
  • Label directly using aria-label

Use a Meter to communicate an amount of something within a range, like number of emails delivered. Use the valueLabel prop on the MeterLabel component to display the current value being represented by the Meter.

Consider what type of value would be most useful for a user to see (for example, “50%” vs. “5,000 of 10,000”). Avoid using multiple formats to represent the same value (for example, "5,000 of 10,000 (50%)").

Component preview theme
const DefaultMeterExample = () => {
const meterId = useUID()
const helpTextId = useUID()
return (
<Box maxWidth="size30">
<MeterLabel htmlFor={meterId} valueLabel="89%">Emails delivered</MeterLabel>
<Meter value={89} id={meterId} />
<HelpText id={helpTextId}>Showing successful deliveries of June email campaign.</HelpText>
</Box>
);
};
render(
<DefaultMeterExample />
)

Meter has a default value of 0, a default minimum value of 0, and a default maximum value of 100.

Passing minValue and maxValue to Meter allow you to set a non 0-100 scale. Use minLabel and maxLabel to display minimum and maximum values below the Meter. If using a non 0-100 scale, displaying min and max labels is required.

Component preview theme
const DefaultMeterExample = () => {
const meterId = useUID()
const helpTextId = useUID()
return (
<Box maxWidth="size60">
<MeterLabel htmlFor={meterId} valueLabel="$4,500.00">Account balance paid</MeterLabel>
<Meter minValue={2000} value={4500} maxValue={50000} minLabel="$2,000.00" maxLabel="$50,000.00" id={meterId}/>
<HelpText id={helpTextId}>Remaining balance must be paid by the end of the billing period. </HelpText>
</Box>
);
};
render(
<DefaultMeterExample />
)

The Meter label should communicate what the Meter is measuring. Where possible, avoid a label that wraps onto two lines.

A Meter almost always will include a numerical value, the value label. When using the valueLabel prop, consider what type of value would be most useful for a user to see. For example, choose either “50%” or “5,000 of 10,000”, not both.

Use Help Text to offer additional information to contextualize or help the user understand the Meter.

Data usage
Do

Use a Meter when a user needs to understand a measurement within a range (like how much data has been used).

File upload status
Don't

Don't use a Meter to represent a path with a completion point (like uploading a file or filling out a form).

Balance
Complete balance due at the end of the billing cycle.
Do

When using a custom value label, use only the format that is the most useful for a user to know.

Balance
Complete balance of $1,500 due at the end of the billing cycle.
Don't

Don't show multiple formats of the same value when possible.