# Meter

A graphical display of a fixed value within a range, e.g. disk usage.

- Category: Core Elements
- Page: https://wunderui.com/components/meter
- Tier: Free

## Install

```bash
npx wunderui-cli add meter
```

## Import

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

## Minimal usage

Then use it:

```tsx
import { Meter, MeterLabel, MeterValue } from "@/components/ui/meter"

export function Storage() {
  return (
    <Meter value={72}>
      <MeterLabel>Storage used</MeterLabel>
      <MeterValue />
    </Meter>
  )
}
```

Expected result: You see the label Storage used with 72% at its right, above a bar that is about three quarters full.

## Usage

```tsx
import { Meter, MeterLabel, MeterValue } from "@/components/ui/meter"

export function Example() {
  return (
    <Meter value={72}>
      <MeterLabel>Storage used</MeterLabel>
      <MeterValue />
    </Meter>
  )
}
```

## When to use

### Use Meter for

- A measured value inside a known range, such as storage used or seats in use
- A score or a quota that is read against its limit
- Several bars that share one limit and are compared with each other

### Use something else

- [Progress](https://wunderui.com/components/progress) for a task that runs to completion, such as an upload or an import
- [Slider](https://wunderui.com/components/slider) for a value the person sets, not one that is shown
- [Skeleton](https://wunderui.com/components/skeleton) for content that is still loading into a layout

## Behavior

What the meter does itself, and what it leaves to the page.

- **Role and value:** Meter has the meter role with a minimum (0 by default), a maximum (100 by default) and the current value, clamped to that range. Its value text is a percent by default; a custom function replaces it.
- **Accessible name:** The meter has no name of its own. A MeterLabel inside it becomes the name, or pass aria-label; MeterValue is hidden from assistive technology, so it is never the name.
- **Always a value:** A meter measures something that exists, so the value is always a number. For a wait of unknown length use Progress with no value, or a Spinner.
- **No states:** A meter has one size and one tone: an 8 px rounded track with a brand-colour fill. It looks the same when full and has no disabled or error look, so say that in text.
- **Format:** Without a format the value prints as a percent: 38 of 50 prints 76%. With a format the value itself prints, for example 38 GB, and MeterValue children can be a function of the formatted and raw value.
- **Motion:** The fill glides to a new value over 700 ms, moving only its transform. The first render draws it at its value without moving.
- **Reduced motion:** With reduced motion the fill jumps to its new value. Colour changes stay.

## Anatomy

- `Meter`: The root: a div with the meter role and its minimum, maximum and current value. Children such as the label and value render above the bar.
- `MeterLabel`: Names what is measured. Without a label, give Meter an aria-label.
- `MeterValue`: Prints the formatted value at the right, a percent of the range by default, in tabular figures. It is hidden from assistive technology because the meter already announces its value.
- `MeterIndicator`: The fill in the brand colour. It glides to a new value over the ambient duration, and Meter already renders it.
- `MeterTrack`: The grey bar behind the fill, 8 px high and fully rounded. Meter renders it; you need it only for a custom layout.

## Best practices

### When to use

- Use a Meter for a measured value inside a known range: storage used, a score, a quota. For a task that runs to completion, use Progress.

### Do

- Name it with MeterLabel or aria-label. Screen readers announce the value, and without a name they cannot say what it measures.
- Set max to the real limit and show the unit: 38 of 50 GB, not a bare 76%. Use the format option or your own text in MeterValue.
- When you print your own text, also pass getAriaValueText so a screen reader hears the same words: 38 of 50 gigabytes. Otherwise it announces the percent.
- Measure bars that belong together against the same max, as in a storage widget, so the fills can be compared.
- Say in words what a full or nearly full meter means and what to do: All seats are in use.

### Don't

- Don't use Meter for task progress. A meter reads as a measurement, so a half-full upload would look like a fixed value: use Progress.
- Don't expect the fill to change colour near the limit. Meter has no low, high or optimum ranges, so tell the person in the text.
- Don't animate the fill width yourself. It already moves with a transform, which is cheaper and matches the other bars.

## API reference

### Meter

| Prop | Type | Default | Description |
|---|---|---|---|
| value* | number |  | The measured value, between `min` and `max`. A value outside the range is clamped. It is always a number: a meter has no indeterminate state. |
| aria-valuetext | React.AriaAttributes['aria-valuetext'] |  | Replaces the text a screen reader announces for the value. The default is the formatted value. |
| className | string \| ((state: State) => string \| undefined) |  | Extra classes, merged with the part's own. A string, or a function of the state. |
| format | Intl.NumberFormatOptions |  | `Intl.NumberFormat` options for the value. Without them the value is printed as a percent of the range; with them the clamped value itself is printed, as in `{ style: "unit", unit: "gigabyte" }`. |
| getAriaValueText | ((formattedValue: string, value: number) => string) |  | Builds the announced text from the formatted value and the raw value, such as `38 of 50 gigabytes`. |
| locale | Intl.LocalesArgument |  | The locale for the formatted value, such as `de-DE`. The default is the locale of the browser. |
| max | number | 100 | The value at which the bar is full: the real limit of what you measure. The default is 100. |
| min | number | 0 | The value at which the bar is empty. The default is 0. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the element of the part with another tag or component. Accepts an element or a function that returns one. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline style for the part, an object or a function of the state. |

Also accepts React.HTMLAttributes attributes.

### MeterIndicator

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes, merged with the part's own. A string, or a function of the state. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the element of the part with another tag or component. Accepts an element or a function that returns one. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline style for the part, an object or a function of the state. |

Also accepts React.HTMLAttributes attributes.

### MeterLabel

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes, merged with the part's own. A string, or a function of the state. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the element of the part with another tag or component. Accepts an element or a function that returns one. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline style for the part, an object or a function of the state. |

Also accepts React.HTMLAttributes attributes.

### MeterTrack

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes, merged with the part's own. A string, or a function of the state. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the element of the part with another tag or component. Accepts an element or a function that returns one. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline style for the part, an object or a function of the state. |

Also accepts React.HTMLAttributes attributes.

### MeterValue

| Prop | Type | Default | Description |
|---|---|---|---|
| children | null \| ((formattedValue: string, value: number) => React.ReactNode) |  | Replaces the printed text with your own. A function gets the formatted value and the raw value, for example `(formatted, value) => value + " of 50 GB"`. |
| className | string \| ((state: State) => string \| undefined) |  | Extra classes, merged with the part's own. A string, or a function of the state. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the element of the part with another tag or component. Accepts an element or a function that returns one. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline style for the part, an object or a function of the state. |

Also accepts React.HTMLAttributes attributes.

## Examples

### Values: a quarter, half, three quarters and full

```tsx
import { Meter, MeterLabel, MeterValue } from "@/components/ui/meter"

export function Example() {
  return (
    <Meter value={25}>
      <MeterLabel>Storage used</MeterLabel>
      <MeterValue />
    </Meter>
  )
}
```

### Content: the bar alone, a label, or a label and its value

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

export function Example() {
  return (
    <Meter aria-label="Storage used" value={72} />
  )
}
```

### Range and format: percent, a unit and your own text

```tsx
import { Meter, MeterLabel, MeterValue } from "@/components/ui/meter"

export function Example() {
  return (
    <Meter value={38} max={50}>
      <MeterLabel>Storage used</MeterLabel>
      <MeterValue />
    </Meter>
  )
}
```

## In context

### Storage widget: three meters against one limit

Every folder is measured against the same 100 GB, so the bars compare at a glance. The card states the total in words.

```tsx
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@/components/ui/card"
import { Meter, MeterLabel, MeterValue } from "@/components/ui/meter"

const LIMIT = 100 // GB

const FOLDERS = [
  { name: "Documents", used: 42 },
  { name: "Media", used: 18 },
  { name: "Backups", used: 8 },
]

export function Example() {
  const used = FOLDERS.reduce((sum, folder) => sum + folder.used, 0)

  return (
    <Card className="w-full max-w-[420px]">
      <CardHeader>
        <CardTitle>Workspace storage</CardTitle>
        <CardDescription>
          {used} GB of {LIMIT} GB
        </CardDescription>
      </CardHeader>
      <CardContent className="flex flex-col gap-4">
        {FOLDERS.map((folder) => (
          <Meter key={folder.name} value={folder.used} max={LIMIT} getAriaValueText={(_formatted, value) => `${value} of ${LIMIT} gigabytes`}>
            <MeterLabel>{folder.name}</MeterLabel>
            <MeterValue>{(_formatted, value) => `${value} GB`}</MeterValue>
          </Meter>
        ))}
      </CardContent>
      <CardFooter className="flex justify-end">
        <Button variant="plain" size="sm">
          Manage storage
        </Button>
      </CardFooter>
    </Card>
  )
}
```

### Seats: a meter that follows a counter

Add or remove a seat and the fill glides to the new value. At the limit the card says so and Add seat turns off.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@/components/ui/card"
import { Meter, MeterLabel, MeterValue } from "@/components/ui/meter"

const SEATS = 10

export function Example() {
  const [used, setUsed] = useState(7)
  const full = used === SEATS

  return (
    <Card className="w-full max-w-[420px]">
      <CardHeader>
        <CardTitle>Team seats</CardTitle>
        <CardDescription>{full ? "All seats are in use." : `${SEATS - used} ${SEATS - used === 1 ? "seat" : "seats"} left`}</CardDescription>
      </CardHeader>
      <CardContent>
        <Meter value={used} max={SEATS} getAriaValueText={(_formatted, value) => `${value} of ${SEATS} seats`}>
          <MeterLabel>Seats in use</MeterLabel>
          <MeterValue>{(_formatted, value) => `${value} of ${SEATS}`}</MeterValue>
        </Meter>
      </CardContent>
      <CardFooter className="flex justify-end gap-2">
        <Button variant="plain" size="sm" disabled={used === 0} onClick={() => setUsed((n) => n - 1)}>
          Remove seat
        </Button>
        <Button variant="plain" size="sm" disabled={full} onClick={() => setUsed((n) => n + 1)}>
          Add seat
        </Button>
      </CardFooter>
    </Card>
  )
}
```

## For AI agents

`get_component("meter")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
