Meter

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add meter

Usage#

Pass value, and min and max when the range is not 0 to 100. A bare <Meter /> renders just the bar; give it an aria-label.

import {
  Meter,
  MeterLabel,
  MeterValue,
  MeterTrack,
  MeterIndicator,
} from "@/components/ui/meter"

export function Example() {
  return (
    <Meter value={64}>
      <MeterLabel>Storage</MeterLabel>
      <MeterValue />
      <MeterTrack>
        <MeterIndicator />
      </MeterTrack>
    </Meter>
  )
}

Anatomy#

import {
  Meter,
  MeterLabel,
  MeterValue,
  MeterTrack,
  MeterIndicator,
} from "@/components/ui/meter"

<Meter>
  <MeterLabel />
  <MeterValue />
  <MeterTrack>
    <MeterIndicator />
  </MeterTrack>
</Meter>

Meter vs Progress#

Progress reports how far a task has got: an upload, an import. It only moves forward and it ends. A meter reports how much of something there is: disk used, seats taken, charge left. It can go down as well as up, and nothing is ever finished. Screen readers hear the difference (role="progressbar" against role="meter"), so pick by meaning, not by look. The two share one bar, so they always sit together cleanly.

Plan usage#

Quotas in a card. Each meter turns warning past 75% and destructive past 90%, and MeterValue phrases the limit next to the reading.

Thresholds#

low, high and optimum work as on the HTML <meter>. They split the range into an optimal, a suboptimal and a critical region, and the fill takes success, warning and destructive. Put optimum at 0 when lower is better (a disk), at the top when higher is better (a battery). The root carries the region as data-level.

Formatted values#

format takes Intl.NumberFormat options and drives both the readout and aria-valuetext. Without it, the reading is a whole percentage of the range; a percent style reads the share of the range too. The visitor’s locale applies after hydration, so the server render never disagrees with the browser. Pass locale to fix one.

Live readings#

The fill glides between readings on the motion tokens, and the readout uses tabular figures so it never jitters as the number changes.

Sizes#

The Progress height scale: xs (4px), sm (the default), md and lg.

Tones#

For a reading with no good or bad side, pin the colour with tone. It wins over the thresholds.

Accessibility#

The root is role="meter" with aria-valuenow, aria-valuemin, aria-valuemax and an aria-valuetext built from format. A composed MeterLabel names it; otherwise pass aria-label. MeterValue is hidden from assistive tech so the reading is not announced twice. Colour is never the only signal: keep the value visible when a threshold matters.

API reference#

FAQ#