Meter | Calcite Design System

Meter is used to represent an available quantity or allotment of a measurable unit.

Overview

Meter can be used to display the amount of a resource remaining, or yet to be used. It can represent the quantity of resource consumed as a value, in relation to min and max limits, and optionally display low and high quantity thresholds to a user.

Meter can also be used to display a count or quantity anytime max is a known value. For instance, Meter is an appropriate way of displaying the number of days in a year that precipitation has been recorded.

Sample

Usage

Display the remaining number of credits or other resource available
Display the amount of storage used on a hard drive
Communicate significant quantity thresholds that could impact a user's experience
Display a count or quantity accrued towards max

Component comparison

While visually similar to Progress, Meter has distinct capabilities and intended use cases.

Meter

This component

Best for displaying an allotment or measured quantity within fixed bounds.

Can represent a resource available or used, or a count accrued toward a known maximum.

The value may fluctuate. min can be less than zero, and max can be greater or less than 100.

Progress

Alternative

Best for representing advancement toward completion of a single task or process.

Often used for system-initiated tasks or processes.

Only value can be set, and it is always a percentage between 0 and 100.

Best Practices

Recommendations

Fill types

Use the appropriate fillType. The default, "range", is useful for providing context about the importance of the current value, for instance if a user is approaching the limit of their available storage. Use "single" when there is no inherent benefit or detriment to the current value.

Do use fillType of "range" when the quantity or allotment could become scarce and negatively impact a user.

Do use fillType of "single" when the current quantity or allotment is strictly informative and has no positive or negative bearing on the user.

Range bounds with `low` and `high`

It is recommended to use low and/or high when they represent quantities of significance. For instance, if the value exceeds high, it may be useful to display corresponding messaging in a Notice, or otherwise communicate the significance to the user.

Once a range threshold is surpassed by the component's value, it is automatically hidden.

Meter showing storage at 100 percent, with a notice that storage is full.

Do populate low or high along with using fillType of "range" if there is a corresponding significance to the values.

Meter showing half of a 12-month range with a threshold at 8 months and a message that the year is halfway done.

Avoid populating low or high and using fillType of "range" if there is no significance to the range.

Label types

The valueLabelType and rangeLabelType properties can be configured as "units" or "percent". The former can be useful when displaying explicit quantities to a user. The latter is often used to simplify complex or lengthy numbers.

It can be valid to use a combination of values, for instance setting rangeLabelType as "percent" and the valueLabelType as "units".

When using valueLabelType or rangeLabelType as "units", it may be useful to use the unitLabel property to provide additional context to a user.

Do use valueLabelType or rangeLabelType of "units", when knowing the explicit number may benefit a user.

Do use valueLabelType or rangeLabelType of "percent" when the numbers are long, or the exact numeric value is not important to a user.

Ensure the unitLabel is concise and provides meaningful context to the user.

Meter showing a value of 25 IBUs on a range from 0 to 100 IBUs.

Do prefer brevity when populating unitLabel.

Meter showing a value of 25 International Bitterness Units on a range from 0 to 100.

Avoid using complex or unnecessarily verbose strings for unitLabel.

API reference

Properties

Property	Attribute	Description	Type	Default
appearance	appearance	Specifies the appearance of the component.	`Extract<"outline" \| "outline-fill" \| "solid", Appearance>`	`"outline-fill"`
disabled	disabled	When `true`, interaction is prevented and the component is displayed with lower opacity.	`boolean`	`false`
fillType	fill-type	Specifies the component's display. `"single"` displays a single color. `"range"` displays a range of colors based on provided `low`, `high`, `min` or `max` values.	`MeterFillType`	`"range"`
form	form	deprecatedin v5.1.0, removal target v6.0.0 - This property has no effect on the component. Specifies the `id` of the component's associated form. When not set, the component is associated with its ancestor form element, if one exists.	`string \| undefined`
groupSeparator	group-separator	When `true`, number values are displayed with a group separator corresponding to the language and country format.	`boolean`	`false`
high	high	Specifies a high value. When `fillType` is `"range"`, displays a different color when above the specified threshold.	`number \| undefined`
labelrequired	label	Specifies an accessible label for the component.	`string`
low	low	Specifies a low value. When `fillType` is `"range"`, displays a different color when above the specified threshold.	`number \| undefined`
max	max	Specifies the component's highest allowed value.	`number`	`100`
min	min	Specifies the component's lowest allowed value.	`number`	`0`
name	name	deprecatedin v5.1.0, removal target v6.0.0 - This property has no effect on the component. Specifies the name of the component. Required to pass the component's `value` on form submission.	`string \| undefined`
numberingSystem	numbering-system	Specifies the Unicode numeral system used by the component for localization.	`NumberingSystem \| undefined`
rangeLabels	range-labels	When `true`, displays the values of `high`, `low`, `min`, and `max`.	`boolean`	`false`
rangeLabelType	range-label-type	When `rangeLabels` is `true`, specifies the format of displayed labels.	`MeterLabelType`	`"percent"`
scale	scale	Specifies the size of the component.	`Scale`	`"m"`
unitLabel	unit-label	When `rangeLabelType` is `"units"` and either `valueLabel` or `rangeLabels` are `true`, displays beside the `value` and/or `min` values.	`string`	`""`
value	value	Specifies the component's value.	`number \| undefined`
valueLabel	value-label	When `true`, displays the `value`.	`boolean`	`false`
valueLabelType	value-label-type	When `valueLabel` is `true`, specifies the format of displayed label.	`MeterLabelType`	`"percent"`

Styles

Name	Description
--calcite-meter-background-color	Specifies the background color of the component.
--calcite-meter-border-color	Specifies the border color of the component and displayed step lines.
--calcite-meter-shadow	Specifies the box shadow of the component.
--calcite-meter-corner-radius	Specifies the corner radius of the component.
--calcite-meter-fill-color	Specifies the color of the component's fill.
--calcite-meter-range-text-color	Specifies the color of the component's range labels.
--calcite-meter-value-text-color	Specifies the color of the component's value label.

Methods

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`