Meter is used to represent an available quantity or allotment of a measurable unit.
Overview
Meter should be used when displaying 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 a
max
Best Practices
While visually similar to Progress, Meter has distinct capabilities and intended use cases.
value can be set. The value is always a percentage between zero and one hundred. Progress should be used to represent system-initiated tasks or processes.min values of less than zero and may have max values of greater or less than one hundred. The value may fluctuate and, when fillType is "range", may convey meaning to the user through use of low and high properties.Recommendations
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 send an email to the user with further communication.
Fill types
Use the appropriate fill. The default, "range", is useful for providing context about the importance of the current value, for example 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.
fillType of "range" when the quantity or allotment could become scarce and negatively impact a user.fillType of "single" when the current quantity or allotment is strictly informative and has no positive or negative bearing on the user.low or high if there is no significance to the range.fillType of "range" when conveying a quantity that has no positive or negative bearing on the user.Label types
The value and range 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 example setting range as "percent" and the value as "units".
When using value or range as "units", it may be useful to use the unit property to provide additional context to a user.
valueLabelType or valueLabelType of "units", when knowing the explicit number may benefit a user.valueLabelType or valueLabelType of "percent" when the numbers are long, or the exact numeric value is not important to a user.unitType.unitType."percent" for valueLabelType when the exact numeric value may be of importance to a user.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, where
"single" displays a single color, and
"range" displays a range of colors based on provided low, high, min or max values. | MeterFillType | "range" |
| form | form | 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 | |
| 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 | |
| label | 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 | |
| max | max | Specifies the component's highest allowed value. | number | 100 |
| min | min | Specifies the component's lowest allowed value. | number | 0 |
| name | name | Specifies the name of the component. Required to pass the component's value on form submission. | string | |
| numberingSystem | numbering-system | Specifies the Unicode numeral system used by the component for localization. | NumberingSystem | |
| 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 | |
| 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 | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<this> |