Meter

Accessible, unstyled native Meter primitive.


Package	`@vizejs/ui/meter`
Maturity	stable
Own the source	`vize lib pull meter`
Requires	id
Aliases	gauge, usage meter, storage meter, threshold meter
Covers	HTML meter element, WAI-ARIA meter role, React Aria Meter

Usage

import { Meter } from "@vizejs/ui/meter";

Or copy the source into your project with vize lib pull meter (see Source Distribution).

API

`Meter`

Source: src/families/feedback/meter/meter.vue

Props

Prop	Type	Default	Description
`id`	`string \| null`	`undefined`	Consumer-owned meter id. `null` and `undefined` select a deterministic fallback.
`value`	`number \| null`	`0`	Current value. Non-finite values are repaired to the normalized minimum.
`min`	`number`	`0`	Lower bound.
`max`	`number`	`1`	Upper bound. Values less than or equal to `min` are repaired to `min + 1`.
`low`	`number \| null`	`null`	Optional low threshold.
`high`	`number \| null`	`null`	Optional high threshold.
`optimum`	`number \| null`	`null`	Optional optimum threshold.
`ariaLabel`	`string`	`undefined`	Accessible name when no visible label or `aria-labelledby` supplies one.
`ariaLabelledby`	`string`	`undefined`	Space-separated ids that label the meter.
`ariaDescribedby`	`string`	`undefined`	Space-separated ids that describe the meter.

Slots

Slot	Slot props	Description
`default`	`MeterSlotState`	Optional fallback contents. Receives normalized Meter state for composition.

Exposed

Member	Type	Description
`value`	`number`	Current finite value clamped to the normalized min/max range.
`min`	`number`	Finite lower bound.
`max`	`number`	Finite upper bound, always greater than `min`.
`low`	`number \| null`	Optional low threshold clamped to the normalized range.
`high`	`number \| null`	Optional high threshold clamped to the normalized range.
`optimum`	`number \| null`	Optional optimum threshold clamped to the normalized range.
`percent`	`number`	Completion percentage from 0 to 100.
`range`	`MeterRange`	Current threshold range.
`optimal`	`boolean`	Whether the current range contains the optimum threshold.
`invalid`	`boolean`	Whether raw inputs had to be repaired before reaching the native element.
`state`	`MeterState`	Stable state token for styling and tests.
`element`	`HTMLMeterElement \| null`	Rendered native meter element.

Behavior

Normative state x input -> outcome table for meter.vue (@vizejs/ui/meter). Every row is proven by the named mounted-DOM, SSR, or compile-time test.

Surface	Contract
Element	`Meter` renders a native `<meter>` with deterministic id, optional ARIA labelling, and no custom focus behavior.
Range	`value`, `min`, and `max` are normalized to a finite native-safe range; `max <= min` is repaired to `min + 1`.
Thresholds	Optional `low`, `high`, and `optimum` thresholds are clamped into range; reversed low/high input is sorted.
State	Slot/expose/data state publishes value, bounds, thresholds, percent, range, optimum match, invalid repair, and token.
Styling	No component CSS is emitted beyond a scoped empty block; `data-vize-ui`, `part`, and `data-*` are the contract.
SSR	Server output is deterministic and contains only native meter attributes, data attributes, and slot text.
Packaging	Root and subpath consumers retain only Meter plus shared deterministic-id support with zero CSS.

State x input	Outcome
finite value inside thresholds	Native `<meter>` receives the same numeric attributes and publishes `data-range` plus normalized percent.
optimum threshold in range	`data-optimal="true"` and `state="optimum"` when the current value is in the same threshold range.
value below min or above max	Value is clamped to the native range and `invalid` is reported for styling and diagnostics.
non-finite or reversed inputs	Unsafe inputs are repaired before reaching the native element and `data-invalid="true"` is published.
omitted thresholds	Threshold attributes are omitted while range state falls back to `medium`, except `empty` and `full`.