Meter

Import

import { Meter } from '@envsemble/envui';

Usage

A Meter takes its value between min, 0 by default, and max, 100 by default; a value outside the range shows, and is reported, as the nearest end. Its label, above the bar, names it, such as Seats assigned. valueText shows the value at the end of the label's row, formatted by the application, such as 2 of 5; without it, no value shows. aria-valuetext is the value as assistive technology reads it, with its unit in words, such as 2 of 5 seats; without it, the value is read as a percentage of the range.

SeatsAssigned.tsx

import { Meter } from '@envsemble/envui';

export default function SeatsAssigned() {
  return (
    <Meter
      label="Seats assigned"
      value={2}
      max={5}
      valueText="2 of 5"
      aria-valuetext="2 of 5 seats"
      style={{ inlineSize: 'min(100%, 20rem)' }}
    />
  );
}

Composition

The parts are the meter, env-meter, its label, env-meter-label, its value, env-meter-value, the track, env-meter-track, and the indicator, env-meter-indicator. className, style, ref and data attributes reach the root, and the numbers follow the provider's locale. The meter has no warning color of its own, so say in text when a limit is reached.

Accessibility

You provide

aria-valuetext with the unit in words, such as 2 of 5 seats; without it, the value is read as a percentage.
Text that says when a limit is reached.

envUI provides

role="meter" named by label, with its value and range, kept within the range.
aria-valuetext from the prop.
No motion under reduced motion.

Props

A measurement within a known range, such as the seats assigned of a plan or the storage used of a quota: a label, an optional value and a bar, exposed as a meter. For how much of a task is done, use Progress.

Prop	Type	Description
`value`required	`number`	The measurement, between min and max. A value outside the range shows, and is reported, as the nearest end.
`label`required	`ReactNode`	What the bar shows, such as Seats assigned; it is visible above the bar and names it.
`min`Default `0`	`number`	The low end of the range.
`max`Default `100`	`number`	The high end of the range.
`valueText`	`ReactNode`	The value as text at the end of the label's row, formatted by the application, such as 2 of 5 or 40%. Without it, no value shows.
`aria-valuetext`	`string`	The value as assistive technology reads it, with its unit in words, such as 2 of 5 seats. Without it, a screen reader reads the value as a percentage of the range, in the locale of the nearest EnvUIProvider.

Also accepts the native props of <div>, such as ref, className and aria-* attributes.

Part names

Each part's class and state attributes are public and versioned, for an application's CSS to style.

env-meter: The meter.
env-meter-header: The row with the label and the value.
env-meter-indicator: The filled part of the track.
env-meter-label: The label.
env-meter-track: The track.
env-meter-value: The value as text.

Changelog

1.0.0: The classes are env-meter*; without aria-valuetext the formatted value stays; className, style, ref and data attributes reach the root, and numbers follow the provider's locale.

In the dark theme, meters reach 3:1 on every surface.
1.0.0-prerelease.6: The track is the neutral fill a Slider's track takes, so it shows on dark panels.