Search docs

Meter

A value within a known range, such as disk usage or battery level.

Meter follows the Meter WAI-ARIA design pattern. Use Progress for the progress of a task.

Storage25%
import { component$, useStyles$ } from '@builder.io/qwik';
import { Meter } from '@leve-ui/meter';
import styles from './default.css?inline';

export default component$(() => {
  useStyles$(styles);

  return (
    <Meter.Root value={25} class="meter-default">
      <Meter.Label class="meter-default-label">Storage</Meter.Label>
      <Meter.ValueText class="meter-default-value" />
      <Meter.Track class="meter-default-track">
        <Meter.Indicator class="meter-default-indicator" />
      </Meter.Track>
    </Meter.Root>
  );
});

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/meter

Anatomy#

import { Meter } from '@leve-ui/meter'; // or '@leve-ui/core'

<Meter.Root>
  <Meter.Label />
  <Meter.ValueText />
  <Meter.Track>
    <Meter.Indicator />
  </Meter.Track>
</Meter.Root>
PartElementDescription
Meter.Root<div>The meter, with role="meter". Holds the value and the range.
Meter.Label<span>The label. Names the Root.
Meter.ValueText<span>Shows the value text (by default, the percentage).
Meter.Track<div>The whole range. Contains the Indicator.
Meter.Indicator<div>The current value. Exposes the percentage as a CSS variable.

Examples#

Controlled#

The value follows a signal. The meter updates when the buttons change it.

Storage50%

With Value Text#

valueText replaces the percentage with a human-readable text, here with max={200}. It is shown by Meter.ValueText and used as aria-valuetext.

Storage50 GB of 200 GB

API Reference#

Root#

PropDefaultType
value (required)–number

The current value. It is clamped between min and max.

min0number

The minimum value.

max100number

The maximum value.

valueText–string

A human-readable text for the value (e.g. "50 GB / 200 GB"), used for aria-valuetext and shown by ValueText. Defaults to the percentage (e.g. "25%").

Also accepts all <div> attributes.

Data attributeValue
data-leve-meterAlways present
data-valueThe value, clamped between min and max
data-minThe min value
data-maxThe max value

value is clamped between min and max.

Label#

No props of its own. Accepts all <span> attributes.

Data attributeValue
data-leve-meter-labelAlways present
data-valueThe clamped value
data-minThe min value
data-maxThe max value

The Label gets a generated id that the Root references with aria-labelledby. If you pass your own id, also pass the same value as aria-labelledby to the Root.

ValueText#

No props of its own. Accepts all <span> attributes.

Data attributeValue
data-leve-meter-value-textAlways present
data-valueThe clamped value
data-minThe min value
data-maxThe max value

Renders the Root's valueText, or the rounded percentage (for example "25%") when it is not set. It has no children.

Track#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-meter-trackAlways present
data-valueThe clamped value
data-minThe min value
data-maxThe max value

Indicator#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-meter-indicatorAlways present
data-valueThe clamped value
data-minThe min value
data-maxThe max value
CSS variableValue
--leve-meter-percentThe value as a percentage of the range, for example 25%

The library does not set a width. Use the variable yourself, for example width: var(--leve-meter-percent).

Accessibility#

Complies with the Meter WAI-ARIA design pattern.

  • Meter.Root renders role="meter" with aria-valuenow, aria-valuemin and aria-valuemax, and aria-valuetext when valueText is set.
  • The Root is named by Meter.Label through aria-labelledby. If you pass aria-label or aria-labelledby to the Root, that is used instead.
  • When the percentage alone does not describe the value (for example, "50 GB of 200 GB"), set valueText.
  • Meter has no keyboard interaction.