Skip to content
WunderUI

Meter

Free

Show a measured value inside a known range, such as storage used or a quota.

npx wunderui-cli add meter

Playground

Storage used
x

Installation

bash
npx wunderui-cli add meter

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import {
  Meter,
  MeterIndicator,
  MeterLabel,
  MeterTrack,
  MeterValue,
} from "@/components/ui/meter"

Then use it:

tsx
import { Meter, MeterLabel, MeterValue } from "@/components/ui/meter"

export function Storage() {
  return (
    <Meter value={72}>
      <MeterLabel>Storage used</MeterLabel>
      <MeterValue />
    </Meter>
  )
}

Expected result: You see the label Storage used with 72% at its right, above a bar that is about three quarters full.

When to use

Use Meter for

  • A measured value inside a known range, such as storage used or seats in use
  • A score or a quota that is read against its limit
  • Several bars that share one limit and are compared with each other

Use something else for

  • Progress for a task that runs to completion, such as an upload or an import
  • Slider for a value the person sets, not one that is shown
  • Skeleton for content that is still loading into a layout

Values

The fill is the value as a share of the range, from min to max. A full meter means the value is at max, not that a task is finished.

Storage used
x

Content

A visible label names what is measured, with the value at its right. Without text, give the bar an aria-label so a screen reader does not announce a bare number.

x

Range and format

Set max to the real limit. The value shows as a percent of the range by default, or as the value itself with a unit, or any text you build.

Storage used
x

Behavior and motion

What the meter does itself, and what it leaves to the page.

Role and value
Meter has the meter role with a minimum (0 by default), a maximum (100 by default) and the current value, clamped to that range. Its value text is a percent by default; a custom function replaces it.
Accessible name
The meter has no name of its own. A MeterLabel inside it becomes the name, or pass aria-label; MeterValue is hidden from assistive technology, so it is never the name.
Always a value
A meter measures something that exists, so the value is always a number. For a wait of unknown length use Progress with no value, or a Spinner.
No states
A meter has one size and one tone: an 8 px rounded track with a brand-colour fill. It looks the same when full and has no disabled or error look, so say that in text.
Format
Without a format the value prints as a percent: 38 of 50 prints 76%. With a format the value itself prints, for example 38 GB, and MeterValue children can be a function of the formatted and raw value.
Motion
The fill glides to a new value over 700 ms, moving only its transform. The first render draws it at its value without moving.
Reduced motion
With reduced motion the fill jumps to its new value. Colour changes stay.

Anatomy

The parts the component is made of. Each one renders a you can target from CSS.

Storage used
x
  • data-slot="meter"

    The root: a div with the meter role and its minimum, maximum and current value. Children such as the label and value render above the bar.

  • data-slot="meter-label"Optional

    Names what is measured. Without a label, give Meter an aria-label.

  • data-slot="meter-value"Optional

    Prints the formatted value at the right, a percent of the range by default, in tabular figures. It is hidden from assistive technology because the meter already announces its value.

  • data-slot="meter-track"Optional

    The grey bar behind the fill, 8 px high and fully rounded. Meter renders it; you need it only for a custom layout.

  • data-slot="meter-indicator"Optional

    The fill in the brand colour. It glides to a new value over the ambient duration, and Meter already renders it.

Best practices

  • Do

    Name it with MeterLabel or aria-label. Screen readers announce the value, and without a name they cannot say what it measures.

  • Do

    Set max to the real limit and show the unit: 38 of 50 GB, not a bare 76%. Use the format option or your own text in MeterValue.

  • Do

    When you print your own text, also pass getAriaValueText so a screen reader hears the same words: 38 of 50 gigabytes. Otherwise it announces the percent.

  • Do

    Measure bars that belong together against the same max, as in a storage widget, so the fills can be compared.

  • Do

    Say in words what a full or nearly full meter means and what to do: All seats are in use.

  • Don’t

    Don't use Meter for task progress. A meter reads as a measurement, so a half-full upload would look like a fixed value: use Progress.

  • Don’t

    Don't expect the fill to change colour near the limit. Meter has no low, high or optimum ranges, so tell the person in the text.

  • Don’t

    Don't animate the fill width yourself. It already moves with a transform, which is cheaper and matches the other bars.

API reference

Every part also takes the props of the Base UI Meter it wraps. The tables list what the page uses; aria props reach the element.

The root: a div with the meter role and its minimum, maximum and current value. Children such as the label and value render above the bar.

PropTypeDefaultDescription
value requirednumber—The measured value, between and . A value outside the range is clamped. It is always a number: a meter has no indeterminate state.
minnumber0The value at which the bar is empty. The default is 0.
maxnumber100The value at which the bar is full: the real limit of what you measure. The default is 100.
formatIntl.NumberFormatOptions— options for the value. Without them the value is printed as a percent of the range; with them the clamped value itself is printed, as in .
localeIntl.LocalesArgument—The locale for the formatted value, such as . The default is the locale of the browser.
aria-valuetextAriaAttributes["aria-valuetext"]—Replaces the text a screen reader announces for the value. The default is the formatted value.
getAriaValueText(formattedValue, value) => string—Builds the announced text from the formatted value and the raw value, such as .
renderReactElement | (props, state) => ReactElement—Replaces the element of the part with another tag or component. Accepts an element or a function that returns one.
classNamestring | (state) => string | undefined—Extra classes, merged with the part's own. A string, or a function of the state.
styleCSSProperties | (state) => CSSProperties | undefined—Inline style for the part, an object or a function of the state.

Names what is measured. Without a label, give Meter an aria-label.

PropTypeDefaultDescription
renderReactElement | (props, state) => ReactElement—Replaces the element of the part with another tag or component. Accepts an element or a function that returns one.
classNamestring | (state) => string | undefined—Extra classes, merged with the part's own. A string, or a function of the state.
styleCSSProperties | (state) => CSSProperties | undefined—Inline style for the part, an object or a function of the state.

Prints the formatted value at the right, a percent of the range by default, in tabular figures. It is hidden from assistive technology because the meter already announces its value.

PropTypeDefaultDescription
childrennull | (formattedValue, value) => ReactNode—Replaces the printed text with your own. A function gets the formatted value and the raw value, for example .
renderReactElement | (props, state) => ReactElement—Replaces the element of the part with another tag or component. Accepts an element or a function that returns one.
classNamestring | (state) => string | undefined—Extra classes, merged with the part's own. A string, or a function of the state.
styleCSSProperties | (state) => CSSProperties | undefined—Inline style for the part, an object or a function of the state.

The fill in the brand colour. It glides to a new value over the ambient duration, and Meter already renders it.

PropTypeDefaultDescription
renderReactElement | (props, state) => ReactElement—Replaces the element of the part with another tag or component. Accepts an element or a function that returns one.
classNamestring | (state) => string | undefined—Extra classes, merged with the part's own. A string, or a function of the state.
styleCSSProperties | (state) => CSSProperties | undefined—Inline style for the part, an object or a function of the state.

The grey bar behind the fill, 8 px high and fully rounded. Meter renders it; you need it only for a custom layout.

PropTypeDefaultDescription
renderReactElement | (props, state) => ReactElement—Replaces the element of the part with another tag or component. Accepts an element or a function that returns one.
classNamestring | (state) => string | undefined—Extra classes, merged with the part's own. A string, or a function of the state.
styleCSSProperties | (state) => CSSProperties | undefined—Inline style for the part, an object or a function of the state.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("meter")
Installnpx wunderui-cli add meter

The full library index for assistants is at /llms.txt.