HyMeter

Usage examples on this page are written for Lit / plain HTML (<hy-meter>). The same component ships as HyMeter in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A measurement within a known range — storage used, a quota, battery, password strength — drawn as a progress bar whose color follows the value. It is the HTML <meter>: low, high and optimum split the range, and the meter is the role color in the good range, warning one range away and danger two ranges away. It renders one hy-progress, so it looks, sizes and themes exactly like one.

Meter or progress?

Ask whether the value moves toward completion. An upload, a set of steps or a sync is progress (hy-progress). A reading that can go up or down and has a good and a bad end — storage used, battery, a score — is a meter.

Color from the value, not the markup

There is no variant: set low, high and optimum and the color follows the value as it changes. Low is good (storage): optimum at min, low where it starts to fill up, high where it gets tight. High is good (battery, strength): optimum at max, high where it starts to drop, low where it gets weak. The derived status is on the host as data-status (default | warning | danger). Set all three for a three-color scale: an optimum on or between low and high makes the middle the good range, so only warning is reachable. Color is never the only signal: show the value (show-value) or say it in the label when it matters.

Accessibility: built in

The host is the meter (ElementInternals) with its value, bounds and value text. formatValue sets both the visible value and what screen readers hear ("8.6 GB of 10 GB").

Accessibility: your part

• Name the meter with label, or with aria-label / aria-labelledby on the host.
• Show the reading as text, with show-value or in the copy beside the meter, and give its unit through formatValue. In forced-colors mode the bar loses its colors, so the text carries the state.

When to use

• A measure inside a known range with a good and a bad end: storage used, a quota, a password's strength.

Do

• Set low, high and optimum so the meter shows when the value is good or bad.
• Show the value next to the bar, with show-value.

When not to use

• A number with no good or bad end, such as a share or a count: show the number as text, or an hy-chart.
• A value people set, such as a volume or a budget cap: hy-slider.

Examples

Storage — low is good

<hy-meter
  label="Storage used"
  value="8.6"
  max="10"
  low="7"
  high="9"
  optimum="0"
  show-value
></hy-meter>

Battery — high is good

<hy-meter label="Battery" value="12" low="20" high="50" optimum="100" show-value></hy-meter>

Formatted value

<hy-meter
  id="storage"
  label="Storage used"
  value="8.6"
  max="10"
  low="7"
  high="9"
  optimum="0"
  show-value
></hy-meter>
<script>
  document.querySelector('#storage').formatValue = (v) => v + ' GB of 10 GB';
</script>

API

Properties

Property	Attribute	Type	Default	Description
value	value	number	0	The measured value. Clamped to [min, max].
min	min	number	0	Lower bound of the range.
max	max	number	100	Upper bound of the range.
low	low	number | undefined	undefined	Where the low region ends (default min).
high	high	number | undefined	undefined	Where the high region starts (default max).
optimum	optimum	number | undefined	undefined	The best value (default the middle of the range). Its region paints the role color.
label	label	string	''	What the meter measures ("Storage used"). Required, or aria-label / aria-labelledby on the host.
showValue	show-value	boolean	false	Show the label and the value (linear), or the value inside the ring.
locale	locale	string | undefined	—	BCP-47 locale for the percentage's digits and sign, shown and announced. Unset, the nearest lang (across shadow roots), else the browser's language.
size	size	'small' | 'medium' | 'large'	'medium'	Size, as on hy-progress.
shape	shape	'linear' | 'ring'	'linear'	Geometry, as on hy-progress: a bar or a ring.
formatValue	—	((value: number) => string) | undefined	undefined	Formats the value for the visible text and for screen readers (aria-valuetext). Without it, both read the percentage of the range.

CSS Parts

Part	Description
base	The progress bar's wrapper
track	The track (linear shape)
indicator	The filled part (linear shape)
ring	The circular wrapper (ring shape)
label-container	The label and value row
label	The label text
value	The value text