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.
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.
Size
Meter comes in three sizes: Small, medium, and large; with large being the default.
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).
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.
Rules For Developers
- Meter won’t display
min>maxranges, so you have to flip them beforehand. - If
valueis outside the range, it will be capped to eitherminormax. In this case,aria-valuetextcontains the original uncapped value, andaria-valuenowthe 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.
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.
With Tooltip
Combining Meter with a block-level Tooltip (<p>, <div>, etc.) works really well.
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.
- Horizontal FunctionCard
- OverviewCard WIP (preview in Storybook)
- TransactionDetail WIP (preview in Storybook)