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 @react-spectrum/meter`
version	3.1.1
usage	`import {Meter} from '@react-spectrum/meter'`

View guidelines

Spectrum

Example#

<Meter label="Storage space" variant="positive" value={35} />

<Meter
  label="Storage space"
  variant="positive"
  value={35}
/>

<Meter
  label="Storage space"
  variant="positive"
  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} variant="positive" />

<Meter
  label="Storage space"
  value={25}
  variant="positive"
/>

<Meter
  label="Storage space"
  value={25}
  variant="positive"
/>

Alternatively, a different scale can be used by setting the minValue and maxValue props.

<Meter
  label="Widgets Used"
  minValue={50}
  maxValue={150}
  value={100}
  variant="positive"
/>

<Meter
  label="Widgets Used"
  minValue={50}
  maxValue={150}
  value={100}
  variant="positive"
/>

<Meter
  label="Widgets Used"
  minValue={50}
  maxValue={150}
  value={100}
  variant="positive"
/>

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}
  variant="positive"
/>

<Meter
  label="Currency"
  formatOptions={{style: 'currency', currency: 'JPY'}}
  value={60}
  variant="positive"
/>

<Meter
  label="Currency"
  formatOptions={{
    style: 'currency',
    currency: 'JPY'
  }}
  value={60}
  variant="positive"
/>

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.

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>

Props#

Name	Type	Default	Description
`variant`	`'positive' \| 'warning' \| 'critical'`	—	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.
`label`	`ReactNode`	—	The content to display as the label.
`showValueLabel`	`boolean`	—	Whether the value's label is displayed. True by default if there's a label, false by default if not.
`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	Default	Description
`flex`	`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`	`number`	—	When used in a flex layout, specifies how the element will grow to fit the space available. See MDN.
`flexShrink`	`number`	—	When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN.
`flexBasis`	`number \| string`	—	When used in a flex layout, specifies the initial main size of the element. See MDN.
`alignSelf`	`'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`	`'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`	`number`	—	The layout order for the element within a flex or grid container. See MDN.
`gridArea`	`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`	`string`	—	When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN.
`gridRow`	`string`	—	When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN.
`gridColumnStart`	`string`	—	When used in a grid layout, specifies the starting column to span within the grid. See MDN.
`gridColumnEnd`	`string`	—	When used in a grid layout, specifies the ending column to span within the grid. See MDN.
`gridRowStart`	`string`	—	When used in a grid layout, specifies the starting row to span within the grid. See MDN.
`gridRowEnd`	`string`	—	When used in a grid layout, specifies the ending row to span within the grid. See MDN.

Spacing

Name	Type	Default	Description
`margin`	`DimensionValue`	—	The margin for all four sides of the element. See MDN.
`marginTop`	`DimensionValue`	—	The margin for the top side of the element. See MDN.
`marginBottom`	`DimensionValue`	—	The margin for the bottom side of the element. See MDN.
`marginStart`	`DimensionValue`	—	The margin for the logical start side of the element, depending on layout direction. See MDN.
`marginEnd`	`DimensionValue`	—	The margin for the logical end side of an element, depending on layout direction. See MDN.
`marginX`	`DimensionValue`	—	The margin for both the left and right sides of the element. See MDN.
`marginY`	`DimensionValue`	—	The margin for both the top and bottom sides of the element. See MDN.

Sizing

Name	Type	Default	Description
`width`	`DimensionValue`	—	The width of the element. See MDN.
`minWidth`	`DimensionValue`	—	The minimum width of the element. See MDN.
`maxWidth`	`DimensionValue`	—	The maximum width of the element. See MDN.
`height`	`DimensionValue`	—	The height of the element. See MDN.
`minHeight`	`DimensionValue`	—	The minimum height of the element. See MDN.
`maxHeight`	`DimensionValue`	—	The maximum height of the element. See MDN.

Positioning

Name	Type	Default	Description
`position`	`'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky'`	—	Specifies how the element is positioned. See MDN.
`top`	`DimensionValue`	—	The top position for the element. See MDN.
`bottom`	`DimensionValue`	—	The bottom position for the element. See MDN.
`left`	`DimensionValue`	—	The left position for the element. See MDN. Consider using `start` instead for RTL support.
`right`	`DimensionValue`	—	The right position for the element. See MDN. Consider using `start` instead for RTL support.
`start`	`DimensionValue`	—	The logical start position for the element, depending on layout direction. See MDN.
`end`	`DimensionValue`	—	The logical end position for the element, depending on layout direction. See MDN.
`zIndex`	`number`	—	The stacking order for the element. See MDN.
`isHidden`	`boolean`	—	Hides the element.

Accessibility

Name	Type	Default	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	Default	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#

View guidelines

<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#

View guidelines

<Flex direction="column" gap="size-300">
  <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="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="positive"
  />
  <Meter
    label="Space used"
    value={90}
    variant="critical"
  />
  <Meter
    label="Space used"
    value={70}
    variant="warning"
  />
</Flex>