Meter

Example

Installation

It lands in components/ui/meter.tsx, with UISet’s root (uiset). Wrap your app in <UISet> once, and every component takes its skin.

What UISet adds

The component is UI SDK’s own, with its parts, props and names, so everything below works as UI SDK documents it. UISet adds the look and checks it:

• Styles in five skins, each in light and dark, from CSS variables you can override.
• Text at 4.5:1 contrast and control edges and focus rings at 3:1, in every skin and theme, checked with axe in tests.
• Haptic cues on phones, and sound cues when you set sound on <UISet>.
• Examples that name every control, so agents can find it (see Agents below).

API Reference

Props are the same as below, as React props.

Meter

• min? (number): The lowest value.
• max? (number): The highest value.
• format? (NumberFormat): How the value reads, for screen readers and the Value part: Intl.NumberFormat options, or a function of the value. A percent style shows where the value sits between min and max; any other style shows the value itself, like { style: "unit", unit: "gigabyte" }.
• locale? (string): The locale the value is formatted in. Defaults to the page's lang, or the browser's language without one, once the page is interactive. Server markup uses English until then, so it never disagrees with the client.
• getValueLabel? (((value: number, details: GaugeLabelDetails<number>) => string)): The text screen readers announce for the value, when the formatted value says too little, like "3 of 12 files". It receives the value, null while a progress bar is indeterminate, and details: the formatted value, its percent, min and max.
• value (number): The reading, between min and max. Outside them, the fill, the percentage and aria-valuenow are clamped, while the state keeps the value as given. A meter always has a value, since there's no busy state.
• debug? (boolean): Logs every state change with its reason to the console, in development builds.

State

What render functions, state-based class names and slots receive. Every part gets the same state.

• value (number): The value, as given.
• percent (number): Where the value sits between min and max, from 0 to 100.

MeterValue adds the formatted text:

• value (number): The value, as given.
• percent (number): Where the value sits between min and max, from 0 to 100.
• text (string): The formatted value, like "40%".

Accessibility

Name the component with MeterLabel or aria-label. It exposes the range and formatted value through the meter role. Use getValueLabel when that value needs more explanation.

Tested Behavior

Every line below is an automated test.

• A meter is named by its label and reads its value.
• The value part shows the formatted value.
• The indicator is as wide as the value.
• A new value updates the meter.
• Min and max set where the value sits.
• A unit format reads the value itself.
• A value label replaces the formatted value for screen readers.
• A value above the maximum reads as the maximum and fills the track.

Runs in React, Vue and web components.

Agents

UI SDK’s agent bridge finds this component by its accessible name: give it a visible label or an aria-label, and an agent can read its state and call its actions without screenshots. Building with AI agents shows how to connect one.

[
  {
    "ref": "c8",
    "component": "meter",
    "actions": [],
    "label": "Storage used",
    "value": 72,
    "min": 0,
    "max": 100
  }
]