# Meter

Measure a current value within a known range.

Storage usage meter

[Complete TSX file](/examples/meter/default.tsx)

```tsx
"use client";

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

export default function Example() {
  return (
    <Meter className="max-w-sm" value={75}>
      <div className="flex justify-between gap-4">
        <MeterLabel>Storage used</MeterLabel>
        <MeterValue />
      </div>
      <MeterTrack>
        <MeterIndicator />
      </MeterTrack>
    </Meter>
  );
}
```

## Installation

Complete [one-time setup](/docs/installation/) first.

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/meter
```

With npm: `npx shadcn@4.18.0 add @siteplane/meter`. [Registry JSON](/registry/meter.json) lists source files and dependencies.

## Usage

```tsx
import { Meter } from "@/siteplane/components/meter";

<Meter value={40} aria-label="Storage used" />;
```

## Composition

```text
Meter
├── MeterLabel
├── MeterValue
└── MeterTrack
    └── MeterIndicator
```

Supplying children replaces the automatic track. Include MeterTrack and MeterIndicator explicitly, as in the first example.

## Range and formatting

Values and formatting belong to the root. This example counts gigabytes instead of percentages and adds the total to the displayed value.

Bandwidth usage in gigabytes

[Complete TSX file](/examples/meter/range.tsx)

```tsx
"use client";

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

export default function Example() {
  return (
    <Meter
      className="max-w-sm"
      value={620}
      max={1000}
      format={{ style: "unit", unit: "gigabyte" }}
    >
      <div className="flex justify-between gap-4">
        <MeterLabel>Monthly bandwidth</MeterLabel>
        <MeterValue>
          {(formattedValue) => `${formattedValue} of 1,000 GB`}
        </MeterValue>
      </div>
      <MeterTrack>
        <MeterIndicator />
      </MeterTrack>
    </Meter>
  );
}
```

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| Meter.size | sm \| md \| lg \| xl | provider / lg | Root size inherited by Label, Track and Value. |
| Meter.tone | accent \| success \| warning \| error | accent | Colors the filled part, for example by strength. accent keeps the progress fill. The earlier names default and destructive still work as deprecated aliases of accent and error. |
| Meter.locale | string | en-US | Explicit kit formatting default; not automatically the locale provider. |
| Meter.children | ReactNode | Track with Indicator | Custom children replace the automatic track. |
| Label / Track / Value.size | sm \| md \| lg \| xl | root / provider / lg | Override the part size. |

`MeterLabel` associates the visible label; `MeterTrack` contains `MeterIndicator`; `MeterValue` formats the current root value; a function child receives the formatted and the raw value. Indicator has no owned props. All styled parts accept string className. Root receives value, min, max, format and accessibility labels from [Base UI Meter](https://base-ui.com/react/components/meter); those numerical and formatting contracts are inherited, not separate Siteplane UI APIs.

`MeterProps`, `MeterLabelProps`, `MeterTrackProps` and `MeterValueProps` export these same size extensions; `MeterProps` adds `tone`: `MeterTone` holds the four current values, and `MeterDeprecatedTone` the two earlier names. `MeterPrimitive` is the foundation namespace.

[Read the installed source](/source/meter).

## Usage notes

Use Progress for task completion; Meter describes a measurement such as capacity or usage. It does not support an unknown/loading state. Without MeterLabel, give the meter an `aria-label`, as in Usage.

At its minimum a meter is empty and shows no fill. Any value above the minimum shows at least a short fill, so a small value stays visible. The fill glides to a new value, and a new tone fades in with it.