# Progress

> Animated progress bar for React and shadcn on Base UI, with a spring-driven bar, a rolling value and an indeterminate sweep.

A progress bar on Base UI Progress: the bar rides a spring that never overshoots, and its value rolls. An unknown length sweeps on an accelerate–decelerate curve and hands over to the bar the moment a value arrives.

Also known as a loading bar.

- Tier: Free (MIT)
- Interaction: Loading
- Page: https://eased.dev/components/progress
- Installs: motion, @base-ui/react
- Registry: https://eased.dev/r/progress.json

## Install

```bash
npx shadcn add https://eased.dev/r/progress.json
```

A progress bar on Base UI's Progress, with a rolling value and an indeterminate sweep that hands over to the bar as soon as a value arrives.

## When to use

- A task with a known length: an upload, an export, a migration, steps of an import.
- A task that starts with an unknown length and learns it later: pass `null` until the first value arrives.
- A quota or usage meter that fills towards a limit, such as storage used.

## When not to use

- A short wait with no measurable progress, inside a button or beside a label: use a [Spinner](/components/spinner).
- Content that is loading into a known layout: use a [Skeleton](/components/skeleton).

## Usage

```tsx upload-progress.tsx
import { Progress } from "@/components/eased/progress/progress";

export function UploadProgress({ sent }: { sent: number | null }) {
  return <Progress label="Launch film final.mov" value={sent} max={842} />;
}
```

## Examples

### Indeterminate

`null` sweeps a segment across the track until the length is known; the value is hidden meanwhile.

```tsx
<Progress label="Processing" value={null} />
```

### Units instead of a percentage

`format` shows and speaks the value itself rather than a percentage.

```tsx
<Progress
  label="Storage"
  value={7.4}
  max={10}
  format={{ style: "unit", unit: "gigabyte", maximumFractionDigits: 1 }}
  successOnComplete={false}
  size="sm"
/>
```

## API reference

### Progress

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `number \| null` | | Current value. `null` is indeterminate. |
| `min` / `max` | `number` | `0` / `100` | |
| `label` | `ReactNode` | | Visible label and the accessible name. |
| `aria-label` | `string` | | The accessible name when there is no `label`. |
| `showValue` | `boolean` | `true` | The rolling value on the right of the label row; hidden while indeterminate. |
| `format` | `Intl.NumberFormatOptions` | whole-number percent | Formats the shown and spoken value. |
| `locale` | `Intl.LocalesArgument` | | |
| `getAriaValueText` | `(formattedValue: string, value: number \| null) => string` | | The spoken value, e.g. `` (f) => `${f} uploaded` ``. |
| `size` | `"sm" \| "md"` | `"md"` | 4px or 6px track. |
| `successOnComplete` | `boolean` | `true` | The bar turns success green at `max`. |
| `className` | `string` | `""` | Appended to the root's classes. |

Values outside `min` and `max` are clamped for the bar and the shown value.

## Accessibility

- Base UI renders `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and `aria-valuetext`; while indeterminate there is no `aria-valuenow`.
- The label names the bar; without a visible label, pass `aria-label`.
- The visible rolling value is hidden from assistive tech, so the value is read once, from the progressbar.

## Motion

The bar rides the smooth spring, which never overshoots, so it never reads past the real value. It is a full-width bar sliding in from the left rather than a growing width, so its rounded end never squashes. The value rolls its digits. An unknown length sweeps a 40% segment across the track every 1.6s on an accelerate–decelerate curve, paused while off-screen, and fades out as the bar fades in the moment a value arrives. Completing turns the bar green over 150ms. Reduced motion: the bar jumps to each value and the sweep becomes a still, faint full-width tint.

## Notes for AI

Use Progress whenever there is a number to show, and pass `null` (not 0) while the length is unknown so it sweeps instead of sitting empty. Give it a `label` that names the task, and `format` when the units mean more than a percentage; turn off `successOnComplete` for meters where full is not success.

Do not animate the value yourself or throttle updates for smoothness: the spring smooths jumps, and the value rolls. Do not swap between a spinner and a bar when the length becomes known; the indeterminate state already hands over.

## Related

- [Spinner](/components/spinner): a wait with nothing to measure.
- [Number Roll](/components/number-roll): the rolling value on its own.
- [Skeleton](/components/skeleton): placeholders for loading content.

## Example

`components/eased/progress/progress-demo.tsx`

```tsx
"use client";

import { useInView } from "motion/react";
import { useEffect, useRef, useState } from "react";
import { Button } from "../button/button";
import { DemoFrame } from "../lib/demo-frame";
import { NumberRoll } from "../number-roll/number-roll";
import { Spinner } from "../spinner/spinner";
import { TextSwap } from "../text-swap/text-swap";
import { Progress } from "./progress";

type Upload = { id: string; name: string; size: number; speed: number };

const FILES: Upload[] = [
  { id: "a", name: "Launch film final.mov", size: 842, speed: 46 },
  { id: "b", name: "Press kit.zip", size: 128, speed: 31 },
  { id: "c", name: "Hero stills.fig", size: 64, speed: 22 },
  { id: "d", name: "Captions (EN, DE, JA).srt", size: 3, speed: 1.4 },
];

/** Megabytes sent per file, then ticks of server-side processing once the bytes are in. */
type State = Record<string, { sent: number; processing: number }>;

const fresh = (): State => Object.fromEntries(FILES.map((f) => [f.id, { sent: 0, processing: 0 }]));
const PROCESSING_TICKS = 6;

export function ProgressDemo() {
  const [state, setState] = useState<State>(fresh);
  const root = useRef<HTMLUListElement>(null);
  const inView = useInView(root);

  // Uneven chunks, the way a real upload reports, then a short indeterminate processing step.
  useEffect(() => {
    if (!inView) return;
    const t = window.setInterval(() => {
      setState((s) => {
        const next = { ...s };
        for (const f of FILES) {
          const cur = s[f.id];
          if (cur.sent < f.size) {
            next[f.id] = { ...cur, sent: Math.min(f.size, cur.sent + f.speed * (0.4 + Math.random())) };
          } else if (cur.processing < PROCESSING_TICKS) {
            next[f.id] = { ...cur, processing: cur.processing + 1 };
          }
        }
        return next;
      });
    }, 450);
    return () => window.clearInterval(t);
  }, [inView]);

  const done = FILES.filter((f) => state[f.id].processing >= PROCESSING_TICKS).length;
  const busy = done < FILES.length;

  return (
    <DemoFrame
      title="Uploads"
      meta={
        <span className="inline-flex items-center gap-1.5">
          {busy && <Spinner size="sm" label={false} />}
          {done} of {FILES.length}
        </span>
      }
      actions={
        <Button variant="ghost" size="sm" edge="end" onClick={() => setState(fresh())}>
          Restart
        </Button>
      }
    >
      <ul ref={root} className="flex flex-col gap-5 p-4">
        {FILES.map((f) => {
          const { sent, processing } = state[f.id];
          const phase = sent < f.size ? "uploading" : processing < PROCESSING_TICKS ? "processing" : "done";
          return (
            <li key={f.id} className="flex flex-col gap-1.5">
              <Progress
                label={f.name}
                value={phase === "processing" ? null : sent}
                max={f.size}
                getAriaValueText={(formatted) => (phase === "processing" ? "Processing" : `${formatted} uploaded`)}
              />
              <div className="flex items-center justify-between text-ui-xs text-text-muted tabular-nums">
                <span>
                  <NumberRoll value={Math.round(Math.min(sent, f.size))} />
                  &nbsp;/&nbsp;{f.size}&nbsp;MB
                </span>
                <Status phase={phase} />
              </div>
            </li>
          );
        })}
      </ul>

      <div className="mt-auto border-t border-line-subtle p-4">
        <Progress label="Workspace storage" value={7.4} max={10} format={{ style: "unit", unit: "gigabyte", maximumFractionDigits: 1 }} size="sm" successOnComplete={false} />
      </div>
    </DemoFrame>
  );
}

function Status({ phase }: { phase: "uploading" | "processing" | "done" }) {
  const text = phase === "uploading" ? "Uploading…" : phase === "processing" ? "Processing…" : "Uploaded";
  return (
    <TextSwap swapKey={phase} className={phase === "done" ? "text-success-text" : ""}>
      {phase === "done" && (
        <svg viewBox="0 0 14 14" aria-hidden className="size-3.5 fill-none stroke-current" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round">
          <path d="M3 7.5 5.75 10 11 4" />
        </svg>
      )}
      {text}
    </TextSwap>
  );
}
```
