Meter

Displays numeric value that varies within a defined range

Import

import { Meter } from "@kobalte/core/meter";
// or
import { Root, Label, ... } from "@kobalte/core/meter";

Features

• Exposed to assistive technology as a meter via ARIA.
• Labeling support for accessibility.
• Internationalized number formatting as a percentage or value.

Anatomy

The meter consists of:

• Meter: The root container for a meter.
• Meter.Label: An accessible label that gives the user information on the meter.
• Meter.ValueLabel: The accessible label text representing the current value in a human-readable format.
• Meter.Track: The component that visually represents the meter track.
• Meter.Fill: The component that visually represents the meter value.

<Meter>
  <Meter.Label />
  <Meter.ValueLabel />
  <Meter.Track>
    <Meter.Fill />
  </Meter.Track>
</Meter>

Example

import { Meter } from "@kobalte/core/meter";

export function BasicExample() {
  return (
    <Meter value={80} class={style.meter}>
      <div class={style["meter__label-container"]}>
        <Meter.Label class={style.meter__label}>Battery Level:</Meter.Label>
        <Meter.ValueLabel class={style["meter__value-label"]} />
      </div>
      <Meter.Track class={style.meter__track}>
        <Meter.Fill class={style.meter__fill} />
      </Meter.Track>
    </Meter>
  );
}

.meter {
  display: flex;
  flex-direction: column;
  gap: 2px;
  width: 300px;
}

.meter__label-container {
  display: flex;
  justify-content: space-between;
}

.meter__label,
.meter__value-label {
  color: hsl(240 4% 16%);
  font-size: 14px;
}

.meter__track {
  height: 10px;
  background-color: hsl(240 6% 90%);
}

.meter__fill {
  background-color: hsl(200 98% 39%);
  height: 100%;
  width: var(--kb-meter-fill-width);
  transition: width 250ms linear;
}

[data-theme*="dark"] .meter__label,
[data-theme*="dark"] .meter__value-label {
  color: hsl(0 100% 100% / 0.9);
}

[data-theme*="dark"] .meter__track {
  background-color: hsl(240 5% 26%);
}

Usage

Custom value scale

By default, the value prop represents the current value of meter, as the minimum and maximum values default to 0 and 100, respectively. Alternatively, a different scale can be used by setting the minValue and maxValue props.

<Meter value={100} minValue={0} maxValue={250} class="meter">
  <div class="meter__label-container">
    <Meter.Label class="meter__label">Disk Space Usage:</Meter.Label>
    <Meter.ValueLabel class="meter__value-label" />
  </div>
  <Meter.Track class="meter__track">
    <Meter.Fill class="meter__fill" />
  </Meter.Track>
</Meter>

Custom value label

The getValueLabel prop allows the formatted value used in Meter.ValueLabel and ARIA to be replaced with a custom string. It receives the current value, min and max values as parameters.

<Meter
  value={3}
  minValue={0}
  maxValue={10}
  getValueLabel={({ value, max }) => `${value} of ${max} tasks completed`}
  class="meter"
>
  <div class="meter__label-container">
    <Meter.Label class="meter__label">Processing...</Meter.Label>
    <Meter.ValueLabel class="meter__value-label" />
  </div>
  <Meter.Track class="meter__track">
    <Meter.Fill class="meter__fill" />
  </Meter.Track>
</Meter>

Meter fill width

We expose a CSS custom property --kb-meter-fill-width which corresponds to the percentage of the meter (ex: 80%). If you are building a linear meter, you can use it to set the width of the Meter.Fill component in CSS.

API Reference

Meter

Meter is equivalent to the Root import from @kobalte/core/meter.

Meter.Label, Meter.ValueLabel, Meter.Track and Meter.Fill shares the same data-attributes.

Rendered elements