Meter

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 />
)

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%)").

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.

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.