Meter

Meters are visual representations of a quantity or an achievement. Their progress is determined by user actions, rather than system actions.

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#

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="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>