Meter
FreeShow a measured value inside a known range, such as storage used or a quota.
npx wunderui-cli add meterPlayground
Installation
npx wunderui-cli add meterWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
Meter,
MeterIndicator,
MeterLabel,
MeterTrack,
MeterValue,
} from "@/components/ui/meter"Then use it:
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
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.
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.
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.
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.
- 1data-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.
- 2data-slot="meter-label"Optional
Names what is measured. Without a label, give Meter an aria-label.
- 3data-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.
- 5data-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.
- 4data-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.
| Prop | Type | Default | Description |
|---|---|---|---|
| value required | number | — | The measured value, between and . A value outside the range is clamped. It is always a number: a meter has no indeterminate state. |
| min | number | 0 | The value at which the bar is empty. The default is 0. |
| max | number | 100 | The value at which the bar is full: the real limit of what you measure. The default is 100. |
| format | Intl.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 . |
| locale | Intl.LocalesArgument | — | The locale for the formatted value, such as . The default is the locale of the browser. |
| aria-valuetext | AriaAttributes["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 . |
| render | ReactElement | (props, state) => ReactElement | — | Replaces the element of the part with another tag or component. Accepts an element or a function that returns one. |
| className | string | (state) => string | undefined | — | Extra classes, merged with the part's own. A string, or a function of the state. |
| style | CSSProperties | (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.
| Prop | Type | Default | Description |
|---|---|---|---|
| render | ReactElement | (props, state) => ReactElement | — | Replaces the element of the part with another tag or component. Accepts an element or a function that returns one. |
| className | string | (state) => string | undefined | — | Extra classes, merged with the part's own. A string, or a function of the state. |
| style | CSSProperties | (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.
| Prop | Type | Default | Description |
|---|---|---|---|
| children | null | (formattedValue, value) => ReactNode | — | Replaces the printed text with your own. A function gets the formatted value and the raw value, for example . |
| render | ReactElement | (props, state) => ReactElement | — | Replaces the element of the part with another tag or component. Accepts an element or a function that returns one. |
| className | string | (state) => string | undefined | — | Extra classes, merged with the part's own. A string, or a function of the state. |
| style | CSSProperties | (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.
| Prop | Type | Default | Description |
|---|---|---|---|
| render | ReactElement | (props, state) => ReactElement | — | Replaces the element of the part with another tag or component. Accepts an element or a function that returns one. |
| className | string | (state) => string | undefined | — | Extra classes, merged with the part's own. A string, or a function of the state. |
| style | CSSProperties | (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.
| Prop | Type | Default | Description |
|---|---|---|---|
| render | ReactElement | (props, state) => ReactElement | — | Replaces the element of the part with another tag or component. Accepts an element or a function that returns one. |
| className | string | (state) => string | undefined | — | Extra classes, merged with the part's own. A string, or a function of the state. |
| style | CSSProperties | (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.
get_component("meter")npx wunderui-cli add meterThe full library index for assistants is at /llms.txt.