Go to Content
Design System
Playroom Storybook
#ClimateEmergency

Meter

Open in Storybook Open in Figma

Meter is used to display a value within a known range, more specifically to indicate some kind of progress. However, we do not use it as an auto-updating progress bar (loading indicator).

Instead, it can be used to display the answer to questions such as:

  • How much money has already been spent on a credit card before reaching the limit?
  • How much money has been allotted to a savings goal?

A basic Meter – with only the required properties specified – looks like this.

Loading demo…

Value

The length of the bar is calculated based on the value property. Fractions are possible. If the value is out of bounds, it is capped, so either no or the full bar is shown.

HINT The example shows the use of percentage values from 0 to 100, but custom ranges are supported.

Loading demo…

Size

Meter comes in three sizes: Small, medium, and large; with large being the default.

Loading demo…

Colour

While Meter comes with a ready-made background, the colour of the bar can be modified (but it cannot be any arbitrary hex value).

Loading demo…

Range

The default meter range represents percentages, i.e. it goes from 0 to 100. But the range can be changed, by setting min and/or max to any value, positive or negative.

Loading demo…
Rules For Developers
  • Meter won’t display min > max ranges, so you have to flip them beforehand.
  • If value is outside the range, it will be capped to either min or max. In this case, aria-valuetext contains the original uncapped value, and aria-valuenow the capped value. See “Meter with a label” on how to use this properly.

With a label

To display the current value also as visible text, add showLabel. Meters with a size below large will ignore this, as they do not have the necessary height. Large meters will show the current percentage followed by a % sign. Percentages will be rounded to not include fractions.

If you need fractions, make sure to additionally specify the value as a properly formatted label. This way, internationalisation is taken care of, as you simply specify the decimal separator.

In the same way, label can also be used to completely deviate from the percentage, by providing custom text instead. Keep in mind that only a few characters will fit due to the limited space.

To override the value read by assistive technology, set screenreaderText. Please do this in case of a custom label text.

Loading demo…
Rules For Designers
  • Up to and including 75%, percentages will be displayed after the bar. Afterwards the label is inside the bar on the left.
  • Meter can handle rich content like an Amount component in its label, but it must not be too complex: For example, a label that provides its own font colour should be avoided, as it won’t pick up the changes in colour that occur after the 75% threshold.

With a secondary value

Meter can take an auxValue which will split the bar into two parts. The initial part will be in the chosen color, followed by another part in a lighter shade, so the auxiliary value specifies the point where the colour switches from the regular colour to its lighter shade. This means min ≤ auxValue ≤ value makes the most sense, but an “improper” auxiliary value will be capped in a similar way to how the primary value is capped.

The main use case is credit card limits, where the regular bar colour indicates the amount already spent, while the lighter bar is attributed to money that has been reserved.

Loading demo…

With Tooltip

Combining Meter with a block-level Tooltip (<p>, <div>, etc.) works really well.

Loading demo…

Actual usage

There is no Meter entry under Examples, but meters are already used in more complex components, so here is a list of these examples.