Meter
meterDisplays a value within a known range using a semantic gauge bar.
Usage
Basic usage
Pass in value to render the measurement bar (default 0–100), and role=meter to express the static quantity ratio.
<Meter value={64} />Labels and values
label and showValue display descriptions and formatted values above the track.
<Meter value={72} label="Disk usage" showValue />Customized range
min/max Customize the upper and lower limits, and the values are converted into proportions according to the interval.
<Meter value={3.6} min={0} max={5} label="Rating" showValue />Absolute wording
formatValue takes over the value text, so the visible string and the aria-valuetext a screen reader announces are one and the same sentence.
<Meter
value={1041}
max={1324}
label="Linked to textbook"
showValue
formatValue={({ value, max }) => `${value} / ${max} questions`}
/>Different proportions
The proportion is determined by value, and the width is calculated internally by Base UI.
<>
<Meter value={18} label="Power" showValue />
<Meter value={100} label="Completion" showValue />
</>When to use
Use Meter for current disk, battery, quota, or other capacity. Meter communicates how full a quantity is now through role="meter"; Progress communicates advancement of a task.
Import
import { Meter } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| value* | number | - | Current value. |
| min | number | 0 | Lower bound. |
| max | number | 100 | Upper bound. |
| showValue | boolean | false | Shows the value text. It reads (value - min) / (max - min) as a percentage, matching the indicator, with at most one decimal. |
| formatValue | (info: { value, min, max, percent }) => string | - | Custom value text. The returned string drives both the visible text and aria-valuetext, so the two can never disagree. percent is already normalized and clamped to 0-100 (not rounded). Use it for absolute wording: ({ value, max }) => \${value} / ${max} questions\``. |
| className | string | - | Custom class, commonly used for width. |
Slots
| Slot | Type | Description |
|---|---|---|
| label | ReactNode | Label such as "Disk usage". This is the only way to give `role="meter"` an accessible name (it is wired through aria-labelledby); without it the meter is unnamed to a screen reader, and a heading you draw yourself does not count. |
Pitfalls
Use Progress for an advancing task, not Meter. The parent determines bar width, so give it an explicit width.
- Only `label` provides the accessible name.
role="meter"is wired to it througharia-labelledby, so a heading rendered outside the component is never associated. - Asserting on `textContent` picks up a stray `x`. Base UI's Meter.Root always appends a visually hidden
<span role="presentation">x</span>; a screen reader ignores it and it never joins the accessible name. Query the specific node instead of reading the whole tree. - A `value` outside `[min, max]` clamps the text to 0-100%, while
aria-valuenowstill reports the raw value. Out-of-range data is yours to fix; the component does not paper over it.
Related
Stat · Statistic · Chart · Timeline · NumberTicker · WorldMap
Playground
<Meter value={64} label="Dosage" showValue />