Meter
Meters are visual representations of a quantity or an achievement. Their progress is determined by user actions, rather than system actions.
| install | yarn add @adobe/react-spectrum |
|---|---|
| added | 3.0.0 |
| usage | import {Meter} from '@adobe/react-spectrum' |
Example#
<Meter label="Storage space" value={35} /><Meter label="Storage space" value={35} /><Meter label="Storage space" value={35} />Value#
Meters are controlled with the value prop. By default, the value prop represents the current percentage of progress, as the minimum and maximum values default to 0 and 100, respectively.
<Meter label="Storage space" value={25} /><Meter label="Storage space" value={25} /><Meter label="Storage space" value={25} />Alternatively, a different scale can be used by setting the minValue and maxValue props.
<Meter label="Widgets Used" minValue={50} maxValue={150} value={100} /><Meter label="Widgets Used" minValue={50} maxValue={150} value={100} /><Meter label="Widgets Used" minValue={50} maxValue={150} value={100} />Values are formatted as a percentage by default, but this can be modified by using the formatOptions prop to specify a different format. formatOptions is compatible with the option parameter of Intl.NumberFormat and is applied based on the current locale.
<Meter label="Currency" formatOptions={{style: 'currency', currency: 'JPY'}} value={60} /><Meter label="Currency" formatOptions={{style: 'currency', currency: 'JPY'}} value={60} /><Meter label="Currency" formatOptions={{ style: 'currency', currency: 'JPY' }} value={60} />Labeling#
Value labels are shown above the Meter by default, but they can also be moved to the side or hidden as needed. The label text should be in sentence case.
<Flex direction="column" maxWidth="size-3000" gap="size-300"> <Meter label="Label" value={25} variant="warning" /> <Meter label="Label" labelPosition="side" value={25} variant="warning" /> <Meter label="Label" showValueLabel={false} value={25} variant="warning" /> </Flex><Flex direction="column" maxWidth="size-3000" gap="size-300" > <Meter label="Label" value={25} variant="warning" /> <Meter label="Label" labelPosition="side" value={25} variant="warning" /> <Meter label="Label" showValueLabel={false} value={25} variant="warning" /> </Flex><Flex direction="column" maxWidth="size-3000" gap="size-300" > <Meter label="Label" value={25} variant="warning" /> <Meter label="Label" labelPosition="side" value={25} variant="warning" /> <Meter label="Label" showValueLabel={false} value={25} variant="warning" /> </Flex>The value label can be updated via the valueLabel prop in cases where showing a different scale makes sense.
<Meter label="Progress" marginBottom="size-300" value={25} valueLabel="1 of 4" variant="warning" /><Meter label="Progress" marginBottom="size-300" value={25} valueLabel="1 of 4" variant="warning" /><Meter label="Progress" marginBottom="size-300" value={25} valueLabel="1 of 4" variant="warning" />By default, the value label is formatted as a percentage. This can be customized using the following props.
showValueLabel: Allows you to display or hide the value label.formatOptions: Allows you to customize the format of the value.valueLabel: Allows you to customize the value label to any string.
<Flex direction="column" maxWidth="size-3000" gap="size-300"> <Meter label="Space used" showValueLabel={false} value={90} variant="critical" /> <Meter label="Space used" valueLabel="54 of 60GB" value={90} variant="critical" /> <Meter label="Space used" formatOptions={{style: 'percent', minimumFractionDigits: 2}} value={89.123} variant="critical" /> </Flex><Flex direction="column" maxWidth="size-3000" gap="size-300" > <Meter label="Space used" showValueLabel={false} value={90} variant="critical" /> <Meter label="Space used" valueLabel="54 of 60GB" value={90} variant="critical" /> <Meter label="Space used" formatOptions={{ style: 'percent', minimumFractionDigits: 2 }} value={89.123} variant="critical" /> </Flex><Flex direction="column" maxWidth="size-3000" gap="size-300" > <Meter label="Space used" showValueLabel={false} value={90} variant="critical" /> <Meter label="Space used" valueLabel="54 of 60GB" value={90} variant="critical" /> <Meter label="Space used" formatOptions={{ style: 'percent', minimumFractionDigits: 2 }} value={89.123} variant="critical" /> </Flex>Accessibility#
Depending on the visualization being used (i.e. depending on the showValueLabel prop), a label, aria-label, or aria-labelledby prop is required.
Internationalization#
To internationalize a Meter, a localized string should be passed to the label prop, aria-label prop, or value of the associated aria-labelledby element.
For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the meter is automatically flipped. In addition, Meter automatically uses the current locale to format the value label.
Props#
| Name | Type | Default | Description |
variant | 'informative' | 'positive' | 'warning' | 'critical' | 'informative' | The visual style of the Meter. |
size | 'S' | 'L' | 'L' | How thick the bar should be. |
labelPosition | LabelPosition | 'top' | The label's overall position relative to the element it is labeling. |
showValueLabel | boolean | — | Whether the value's label is displayed. True by default if there's a label, false by default if not. |
label | ReactNode | — | The content to display as the label. |
formatOptions | Intl.NumberFormatOptions | {style: 'percent'} | The display format of the value label. |
valueLabel | ReactNode | — | The content to display as the value's label (e.g. 1 of 4). |
value | number | 0 | The current value (controlled). |
minValue | number | 0 | The smallest value allowed for the input. |
maxValue | number | 100 | The largest value allowed for the input. |
Layout
| Name | Type | Description |
flex | Responsive<string | number | boolean> | When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN. |
flexGrow | Responsive<number> | When used in a flex layout, specifies how the element will grow to fit the space available. See MDN. |
flexShrink | Responsive<number> | When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN. |
flexBasis | Responsive<number | string> | When used in a flex layout, specifies the initial main size of the element. See MDN. |
alignSelf | Responsive<'auto' | 'normal' | 'start' | 'end' | 'center' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'stretch'> | Overrides the alignItems property of a flex or grid container. See MDN. |
justifySelf | Responsive<'auto' | 'normal' | 'start' | 'end' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'center' | 'left' | 'right' | 'stretch'> | Specifies how the element is justified inside a flex or grid container. See MDN. |
order | Responsive<number> | The layout order for the element within a flex or grid container. See MDN. |
gridArea | Responsive<string> | When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN. |
gridColumn | Responsive<string> | When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN. |
gridRow | Responsive<string> | When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN. |
gridColumnStart | Responsive<string> | When used in a grid layout, specifies the starting column to span within the grid. See MDN. |
gridColumnEnd | Responsive<string> | When used in a grid layout, specifies the ending column to span within the grid. See MDN. |
gridRowStart | Responsive<string> | When used in a grid layout, specifies the starting row to span within the grid. See MDN. |
gridRowEnd | Responsive<string> | When used in a grid layout, specifies the ending row to span within the grid. See MDN. |
Spacing
| Name | Type | Description |
margin | Responsive<DimensionValue> | The margin for all four sides of the element. See MDN. |
marginTop | Responsive<DimensionValue> | The margin for the top side of the element. See MDN. |
marginBottom | Responsive<DimensionValue> | The margin for the bottom side of the element. See MDN. |
marginStart | Responsive<DimensionValue> | The margin for the logical start side of the element, depending on layout direction. See MDN. |
marginEnd | Responsive<DimensionValue> | The margin for the logical end side of an element, depending on layout direction. See MDN. |
marginX | Responsive<DimensionValue> | The margin for both the left and right sides of the element. See MDN. |
marginY | Responsive<DimensionValue> | The margin for both the top and bottom sides of the element. See MDN. |
Sizing
| Name | Type | Description |
width | Responsive<DimensionValue> | The width of the element. See MDN. |
minWidth | Responsive<DimensionValue> | The minimum width of the element. See MDN. |
maxWidth | Responsive<DimensionValue> | The maximum width of the element. See MDN. |
height | Responsive<DimensionValue> | The height of the element. See MDN. |
minHeight | Responsive<DimensionValue> | The minimum height of the element. See MDN. |
maxHeight | Responsive<DimensionValue> | The maximum height of the element. See MDN. |
Positioning
| Name | Type | Description |
position | Responsive<'static' | 'relative' | 'absolute' | 'fixed' | 'sticky'> | Specifies how the element is positioned. See MDN. |
top | Responsive<DimensionValue> | The top position for the element. See MDN. |
bottom | Responsive<DimensionValue> | The bottom position for the element. See MDN. |
left | Responsive<DimensionValue> | The left position for the element. See MDN. Consider using start instead for RTL support. |
right | Responsive<DimensionValue> | The right position for the element. See MDN. Consider using start instead for RTL support. |
start | Responsive<DimensionValue> | The logical start position for the element, depending on layout direction. See MDN. |
end | Responsive<DimensionValue> | The logical end position for the element, depending on layout direction. See MDN. |
zIndex | Responsive<number> | The stacking order for the element. See MDN. |
isHidden | Responsive<boolean> | Hides the element. |
Accessibility
| Name | Type | Description |
id | string | The element's unique identifier. See MDN. |
aria-label | string | Defines a string value that labels the current element. |
aria-labelledby | string | Identifies the element (or elements) that labels the current element. |
aria-describedby | string | Identifies the element (or elements) that describes the object. |
aria-details | string | Identifies the element (or elements) that provide a detailed, extended description for the object. |
Advanced
| Name | Type | Description |
UNSAFE_className | string | Sets the CSS className for the element. Only use as a last resort. Use style props instead. |
UNSAFE_style | CSSProperties | Sets inline style for the element. Only use as a last resort. Use style props instead. |
Visual options#
Size#
<Flex direction="column" gap="size-300"> <Meter label="Space used" size="S" value={90} variant="critical" /> <Meter label="Space used" size="L" value={90} variant="critical" /> </Flex><Flex direction="column" gap="size-300"> <Meter label="Space used" size="S" value={90} variant="critical" /> <Meter label="Space used" size="L" value={90} variant="critical" /> </Flex><Flex direction="column" gap="size-300" > <Meter label="Space used" size="S" value={90} variant="critical" /> <Meter label="Space used" size="L" value={90} variant="critical" /> </Flex>Variants#
<Flex direction="column" gap="size-300"> <Meter label="Space used" value={25} variant="informative" /> <Meter label="Space used" value={25} variant="positive" /> <Meter label="Space used" value={90} variant="critical" /> <Meter label="Space used" value={70} variant="warning" /> </Flex><Flex direction="column" gap="size-300"> <Meter label="Space used" value={25} variant="informative" /> <Meter label="Space used" value={25} variant="positive" /> <Meter label="Space used" value={90} variant="critical" /> <Meter label="Space used" value={70} variant="warning" /> </Flex><Flex direction="column" gap="size-300" > <Meter label="Space used" value={25} variant="informative" /> <Meter label="Space used" value={25} variant="positive" /> <Meter label="Space used" value={90} variant="critical" /> <Meter label="Space used" value={70} variant="warning" /> </Flex>