Meter

Meter communicates a known numeric value within a fixed range, such as usage, capacity, a rating, or a quota.

Purpose

Meter communicates a known numeric value within a fixed range, such as storage usage, capacity, a rating, or a quota. Use Progress for an ongoing task whose completion is changing over time.

Bounded value

API usage

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

export function Example() {
  return (
    <Meter value={72}>
      <div><MeterLabel>Usage</MeterLabel><MeterValue /></div>
      <MeterTrack><MeterIndicator /></MeterTrack>
    </Meter>
  );
}

Installation

With the Siteplane registry alias configured, add the component and import the installed source from your app.

CLI

pnpm dlx shadcn@4.16.1 add @siteplane/meter

Import

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

Need the machine-readable source metadata? View registry JSON.

Usage

Meter shows a bounded measurement. Use Progress for task completion and Meter for health, usage or quality values.

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

export function Example() {
  return (
    <Meter value={72}>
      <div><MeterLabel>Usage</MeterLabel><MeterValue /></div>
      <MeterTrack><MeterIndicator /></MeterTrack>
    </Meter>
  );
}

Examples

Value states, hidden labels, formatted values, custom ranges and sizes are props of the same primitive.

Value states

Empty and full are plain values — layout and structure stay the same.

Quota usage

Capacity

{/* Empty */}
<Meter value={0}>
  <div className="flex items-center justify-between gap-2">
    <MeterLabel>Quota usage</MeterLabel>
    <MeterValue />
  </div>
  <MeterTrack><MeterIndicator /></MeterTrack>
</Meter>

{/* Full */}
<Meter value={100}>
  <div className="flex items-center justify-between gap-2">
    <MeterLabel>Capacity</MeterLabel>
    <MeterValue />
  </div>
  <MeterTrack><MeterIndicator /></MeterTrack>
</Meter>

Without label

Without children the root renders track and indicator automatically; keep an aria-label on the bar.

<Meter aria-label="Storage usage" value={50} />

Formatted value

MeterValue accepts a render function when percent is not the right unit.

Rating

<Meter max={5} value={3}>
  <div className="flex items-center justify-between gap-2">
    <MeterLabel>Rating</MeterLabel>
    <MeterValue>{(_formatted, value) => `${value} / 5`}</MeterValue>
  </div>
  <MeterTrack>
    <MeterIndicator />
  </MeterTrack>
</Meter>

Custom range

min and max define the range the indicator maps the value into.

Bandwidth (Mbps)

<Meter max={1000} min={500} value={700}>
  <div className="flex items-center justify-between gap-2">
    <MeterLabel>Bandwidth (Mbps)</MeterLabel>
    <MeterValue>{(_formatted, value) => value}</MeterValue>
  </div>
  <MeterTrack>
    <MeterIndicator />
  </MeterTrack>
</Meter>

Sizes

sm and default share the same track height — the root gap and value text scale with the size.

Small

Default

Large

Extra large

<Meter size="sm" value={72}>...</Meter>
<Meter value={72}>...</Meter>
<Meter size="lg" value={72}>...</Meter>
<Meter size="xl" value={72}>...</Meter>

API Reference

The reference lists the source-owned exports and props that are easy to miss in visual examples. Inherited Base UI props remain available unless the wrapper narrows them.

Set value, optional min and max, and controlled or formatted value behavior on Meter.
locale controls the formatted numeric output and defaults to "en-US".
Compose MeterLabel, MeterValue, MeterTrack, and MeterIndicator for a labelled measurement. Without children, Meter renders its Track and Indicator automatically.
Root size accepts "sm", "default", "lg", or "xl" and provides the default size to every part.
MeterLabel, MeterTrack, and MeterValue each accept their own size override. A part-level size takes precedence over the root or provider size.
MeterValue accepts the Base UI render function when the displayed unit is not a percentage.

Motion

Component motion uses the shared Siteplane motion contract. See the global motion guide for provider setup, tokens and reduced-motion behavior.

MeterIndicator animates value changes with the central linger duration and Apple-out easing tokens.
The operating-system reduced-motion preference removes the transition. The forced reducedMotionPreset shortens the shared linger duration from 380ms to 120ms.
Value updates do not change the surrounding layout.

Accessibility

Provide a visible MeterLabel or an explicit accessible name.
Preserve aria-valuenow, aria-valuemin, and aria-valuemax from the Base UI-backed root.
A custom MeterValue format must communicate the same numeric state as the indicator.
Meter is read-only. Use Slider or Number Field when a person must change the value.

Implementation Guidance

Use Meter only when the current value, minimum, and maximum are known.
Use Progress for task completion and Slider or Number Field for input.
Keep Track, Indicator, locale, size inheritance, and accessibility behavior inside the existing primitive.
Do not rebuild the visual from a raw progress element when Meter fits.