# Progress and meter

> Progress shows task completion; Meter shows a measurement against its range and limit.

Category: Feedback · Atomic level: atom · Built on Base UI Progress, Meter
Page: https://ui.dtheo.dev/docs/components/progress

## Install

```bash
npx dtheo@latest add progress
# or, with the shadcn CLI
npx shadcn@latest add https://ui.dtheo.dev/r/progress.json
```

Dependencies: @base-ui/react, clsx, tailwind-merge. Registry dependencies: utils.

## Exports

`Progress`, `Meter`

## Use it for

- Upload or analysis progress
- Load, temperature or current against a limit

## Reach for something else

- Waits under ~300 ms: show nothing
- Unknown duration presented as a percentage: pass value={null}

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| null` | – | Progress: null for indeterminate work. Never fake a percentage. |
| `limit` | `number` | – | Meter: draws a tick at the limit. |
| `tone` | `'neutral' \| 'primary' \| 'success' \| 'warning' \| 'destructive'` | `'primary'` | Meter: fill severity. Pair it with a word or icon. |
| `unit` | `string` | – | Shown after the value when showValue is on, for units Intl cannot format (A, N·m). |

## Accessibility

- Indeterminate progress (`value={null}`) is honest when the duration is unknown; never fake a percentage.

## Examples

### progress-meter

```tsx
import { Meter, Progress } from '@/components/ui/progress';

export default function ProgressMeterExample() {
  return (
    <div className="grid w-full max-w-xl gap-x-10 gap-y-6 sm:grid-cols-2">
      <section aria-label="Task progress" className="flex flex-col gap-4">
        <h3 className="text-caption font-semibold text-subtle-foreground">Progress: work getting done</h3>
        <Progress label="Uploading R-0412 traces" value={64} showValue />
        {/* The duration is unknown, so no percentage. */}
        <Progress label="Computing efficiency map" value={null} />
      </section>
      <section aria-label="Measurements" className="flex flex-col gap-4">
        <h3 className="text-caption font-semibold text-subtle-foreground">
          Meter: a measurement against its limit
        </h3>
        <Meter
          label="Winding temperature"
          value={71.2}
          max={120}
          limit={90}
          tone="neutral"
          showValue
          format={{ style: 'unit', unit: 'celsius', maximumFractionDigits: 1 }}
        />
        <div className="flex flex-col gap-1.5">
          <Meter
            label="Phase current"
            value={37.6}
            max={50}
            limit={40}
            tone="warning"
            showValue
            unit="A"
            getAriaValueText={(_, value) => `${value} amperes, near the 40 ampere limit`}
          />
          <p className="text-caption text-warning-foreground">Near the 40 A limit</p>
        </div>
      </section>
    </div>
  );
}
```

## Used in

- Lab assistant (page): https://ui.dtheo.dev/examples/assistant
- States pattern (template): https://ui.dtheo.dev/docs/patterns/states
