# Progress

A horizontal bar showing completion of a task.

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

## Install

```bash
npx wunderui-cli add progress
```

## Import

```tsx
import { Progress, HistogramBar, ProgressCell, ProgressIndicator, ProgressLabel, ProgressRow, ProgressRowProps, ProgressTrack, ProgressValue, ProgressValuePosition } from "@/components/ui/progress"
```

## Minimal usage

Then use it:

```tsx
import { Progress, ProgressLabel } from "@/components/ui/progress"

export function Upload() {
  return (
    <Progress value={50} valuePosition="right">
      <ProgressLabel>Uploading report.pdf</ProgressLabel>
    </Progress>
  )
}
```

Expected result: You should see the label Uploading report.pdf above a bar that is half full, with 50% at its right.

## Usage

```tsx
import { Progress, ProgressLabel } from "@/components/ui/progress"

export function Example() {
  return (
    <Progress value={50} valuePosition="right">
      <ProgressLabel>Uploading report.pdf</ProgressLabel>
    </Progress>
  )
}
```

## When to use

### Use Progress for

- A task that runs to completion and whose progress you know, such as an upload or an import
- A run of steps, such as a setup checklist, with the count of steps done as the value
- A queue where every item has its own bar and its own status

### Use something else

- [Meter](https://wunderui.com/components/meter) for a measured value inside a range, such as storage used or a quota
- [Spinner](https://wunderui.com/components/spinner) for a wait of unknown length that has no value to show
- [Skeleton](https://wunderui.com/components/skeleton) for content that is still loading into a layout

## Behavior

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

- **Role and value:** Progress is a progressbar with a min (default 0), a max (default 100) and the value clamped to that range. The announced text is a percent of the range by default; you can replace it.
- **Accessible name:** The bar has no name of its own: a label inside it becomes the name, and without one you pass an aria-label. The value part is hidden from assistive technology, so it is never the name.
- **Indeterminate:** A null value marks a bar whose progress is unknown. The fill has no width and nothing moves, so show activity another way, with a Spinner or a message.
- **Complete:** When the value reaches the max, the parts are marked complete; below it, progressing. The bar does not change colour: say that the task is done in the label.
- **Size and tone:** One size and one tone: the track is 6 px high and fully rounded, and the fill uses the brand colour. There is no error variant, so tell a failure in words next to the bar.
- **Value position:** With a value position the value sits in a 40 px column right or left of the track, below it, or in a dark bubble that follows the fill. The bubble is hidden from assistive technology.
- **Motion:** When the value changes the fill glides over 700 ms and only the transform moves; the first render draws it at its value without moving. The bubble moves to its new place at once.
- **Reduced motion:** With reduced motion the fill jumps to its new value. Colour changes stay.

## Anatomy

- `Progress`: The root: a progressbar with its min, max and current value set, and children such as the label render above the bar. The value can sit right or left of the bar, below it, or in a bubble.
- `ProgressLabel`: Names the task, and Progress points to it as its label. Without a label, give Progress an aria-label.
- `ProgressIndicator`: The fill, in the brand colour, drawn at full width and scaled to the value so it glides to a new one. Progress already renders it; with a null value it has no width.
- `ProgressTrack`: The grey bar behind the fill: 6 px high and fully rounded. Progress already renders it; you only need it for a custom layout.
- `ProgressValue`: Prints the formatted value, a percent of the range by default, in tabular figures. It is hidden from assistive technology, because the bar already announces its value.
- `ProgressCell`
- `ProgressRow`: One line of a breakdown, such as a rating distribution or the share of a channel: the label with an optional icon, an 8 px bar and the share at the end. The row reads as one image. It replaces HistogramBar.
- `HistogramBar`
- `Bubble`

## Best practices

### When to use

- Use Progress for a task that runs to completion: an upload, an import, a run of setup steps. For a fixed value inside a range, such as storage used, use Meter.

### Do

- Name the bar with a label, such as Uploading report.pdf. Screen readers then say what is progressing, not only the number.
- Add the value part when the number matters. It formats the value in tabular figures, so the text does not jump while it counts.
- Put the value where it is read first: right for a compact row, bottom when the bar spans the full width, or a bubble when the number should follow the end of the fill.
- Set the max to the number of steps when the task has steps, and pass the steps done as the value, such as 3 of 5. The bar then needs no sum of its own.
- When you print your own text, also pass a value text for screen readers, such as 3 of 5 steps. Otherwise it announces the percent.
- Say a failure in words next to the bar and offer the next action, such as Failed, retry. The bar keeps the value where the task stopped.

### Don't

- Don't animate the width of the fill yourself. The indicator already scales smoothly.
- Don't use an indeterminate bar for a long wait on its own. It draws no fill and no motion, so pair it with a Spinner or a message.
- Don't show a bar for a measured value such as storage used, since it would announce a task that is never finished. Use Meter.

## API reference

### Progress

| Prop | Type | Default | Description |
|---|---|---|---|
| value* | number \| null |  | How far the task has come, between `min` and `max`. A value outside the range is clamped. `null` marks the bar indeterminate: it has no `aria-valuenow` and draws no fill. |
| aria-valuetext | React.AriaAttributes['aria-valuetext'] |  | Replaces the text a screen reader announces for the value. The default is the formatted value, or `indeterminate progress` without a value. |
| className | string \| ((state: State) => string \| undefined) |  | Extra classes, merged with the part's own. A string, or a function of the state (`progressing`, `complete`, `indeterminate`). |
| 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: "megabyte" }`. |
| getAriaValueText | ((formattedValue: string, value: number \| null) => string) |  | Builds the announced text from the formatted value and the raw value, such as `3 of 5 steps`. It is called with `null` as the value while the bar is indeterminate. |
| 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 task is complete. The default is 100. Set it to the number of steps to count steps. |
| 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. |
| valuePosition | "left" \| "right" \| "bottom" \| "tooltip-top" \| "tooltip-bottom" |  | Prints the value with the bar: `right` or `left` in a row with the track, `bottom` below it, `tooltip-top` or `tooltip-bottom` in a bubble that follows the end of the fill. Leave it out to place `ProgressValue` yourself among the children. |

Also accepts React.HTMLAttributes attributes.

### HistogramBar

| Prop | Type | Default | Description |
|---|---|---|---|
| label* | React.ReactNode |  | The row's name, usually the star count (5). |
| value* | number |  | Share of the bar, 0 to 100 (clamped). |
| aria-label | string |  | Name of the whole row for assistive tech. Default: "5 stars: 78%", built from the label and the end text. |
| className | string |  |  |
| count | React.ReactNode |  | Shown at the end of the row instead of the rounded percentage (for example a review count). |

### ProgressCell

| Prop | Type | Default |
|---|---|---|
| value* | number |  |

### ProgressIndicator

| 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 (`progressing`, `complete`, `indeterminate`). |
| 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.

### ProgressLabel

| 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 (`progressing`, `complete`, `indeterminate`). |
| 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.

### ProgressRow

| Prop | Type | Default | Description |
|---|---|---|---|
| label* | React.ReactNode |  | The name of the row at the start, such as a star level or a channel. Required. |
| value* | number |  | The share of the bar, 0 to 100. Values outside the range are clamped. Required. |
| aria-label | string |  | The name of the whole row. By default it is built from the label and the end text. |
| className | string |  | Extra classes on the row. |
| icon | React.ReactNode |  | A small mark after the label, such as a star. |
| tone | "primary" \| "yellow" | "primary" | The fill colour: `primary` (default) or `yellow`, the colour of a rating. |
| valueText | React.ReactNode |  | Shown at the end instead of the rounded percentage, for example a review count. |

### ProgressTrack

| 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 (`progressing`, `complete`, `indeterminate`). |
| 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.

### ProgressValue

| Prop | Type | Default | Description |
|---|---|---|---|
| children | null \| ((formattedValue: string \| null, value: number \| null) => React.ReactNode) |  | Replaces the printed text with your own. A function gets the formatted value (the word `indeterminate` while the bar is indeterminate) and the raw value, for example `(formatted, value) => value + " of 5"`. |
| className | string \| ((state: State) => string \| undefined) |  | Extra classes, merged with the part's own. A string, or a function of the state (`progressing`, `complete`, `indeterminate`). |
| 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

### Types: where the value is printed

```tsx
import { Progress } from "@/components/ui/progress"

export function Example() {
  return (
    <Progress aria-label="Upload progress" value={48} />
  )
}
```

### Content: the name of the task and its value

```tsx
import { Progress, ProgressLabel } from "@/components/ui/progress"

export function Example() {
  return (
    <Progress value={64}>
      <ProgressLabel>Uploading report.pdf</ProgressLabel>
    </Progress>
  )
}
```

### Range and format: percent, steps and a size

```tsx
import { Progress, ProgressLabel, ProgressValue } from "@/components/ui/progress"

export function Example() {
  return (
    <Progress value={48}>
      <ProgressLabel>Importing contacts</ProgressLabel>
      <ProgressValue />
    </Progress>
  )
}
```

### States: in progress, complete and indeterminate

```tsx
import { Progress, ProgressLabel, ProgressValue } from "@/components/ui/progress"

export function Example() {
  return (
    <Progress value={48}>
      <ProgressLabel>Uploading report.pdf</ProgressLabel>
      <ProgressValue />
    </Progress>
  )
}
```

### Row: a label, a bar and the share

```tsx
import { Star } from "lucide-react"
import { ProgressRow } from "@wunderui/react"

const rows = [
  { stars: 5, share: 78 },
  { stars: 4, share: 14 },
  { stars: 3, share: 5 },
  { stars: 2, share: 2 },
  { stars: 1, share: 1 },
]

export function RatingBreakdown() {
  return (
    <div className="flex flex-col gap-2">
      {rows.map((row) => (
        <ProgressRow
          key={row.stars}
          label={row.stars}
          icon={<Star className="size-2.5 fill-brand-quaternary text-brand-quaternary" strokeWidth={1.5} />}
          value={row.share}
          tone="yellow"
          aria-label={`${row.stars} stars: ${row.share}%`}
        />
      ))}
    </div>
  )
}
```

## In context

### Upload: a file with its value at the right

The bar follows a counter. Pause holds it, Restart starts again, and the card names the state in words.

```tsx
import { useEffect, useState } from "react"
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@/components/ui/card"
import { Progress } from "@/components/ui/progress"

const SIZE = 9.1 // MB

export function Example() {
  const [value, setValue] = useState(32)
  const [running, setRunning] = useState(true)
  const complete = value >= 100

  useEffect(() => {
    if (!running || complete) return
    const id = window.setInterval(() => setValue((v) => Math.min(100, v + 8)), 800)
    return () => window.clearInterval(id)
  }, [running, complete])

  const status = complete ? "Complete" : running ? "Uploading" : "Paused"

  return (
    <Card className="w-full max-w-[420px]">
      <CardHeader>
        <CardTitle>Q3-report.pdf</CardTitle>
        <CardDescription>
          {((value * SIZE) / 100).toFixed(1)} MB of {SIZE} MB · {status}
        </CardDescription>
      </CardHeader>
      <CardContent>
        <Progress aria-label="Upload progress for Q3-report.pdf" value={value} valuePosition="right" />
      </CardContent>
      <CardFooter className="flex justify-end gap-2">
        {!complete && (
          <Button variant="plain" size="sm" onClick={() => setRunning((r) => !r)}>
            {running ? "Pause" : "Resume"}
          </Button>
        )}
        <Button
          variant="plain"
          size="sm"
          onClick={() => {
            setValue(0)
            setRunning(true)
          }}
        >
          Restart
        </Button>
      </CardFooter>
    </Card>
  )
}
```

### Setup checklist: the bar below counts the steps done

The value is the number of steps done and max the number of steps, so the bar needs no sum of its own.

```tsx
import { useId, useState } from "react"
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
import { Checkbox } from "@/components/ui/checkbox"
import { Label } from "@/components/ui/label"
import { Progress } from "@/components/ui/progress"

const STEPS = [
  "Create your workspace",
  "Invite a teammate",
  "Connect a data source",
  "Set up billing",
  "Publish your first page",
]

export function Example() {
  const id = useId()
  const [done, setDone] = useState([true, true, true, false, false])
  const count = done.filter(Boolean).length

  return (
    <Card className="w-full max-w-[420px]">
      <CardHeader>
        <CardTitle>Set up WunderUI</CardTitle>
        <CardDescription>
          {count} of {STEPS.length} steps done
        </CardDescription>
      </CardHeader>
      <CardContent className="flex flex-col gap-4">
        <Progress aria-label="Setup progress" value={count} max={STEPS.length} valuePosition="bottom" />
        <ul className="flex flex-col gap-3">
          {STEPS.map((step, index) => (
            <li key={step} className="flex items-center gap-3">
              <Checkbox
                id={`${id}-${index}`}
                checked={done[index]}
                onCheckedChange={(checked) => setDone((list) => list.map((value, i) => (i === index ? checked : value)))}
              />
              <Label htmlFor={`${id}-${index}`}>{step}</Label>
            </li>
          ))}
        </ul>
      </CardContent>
    </Card>
  )
}
```

### Import queue: one bar per file

Each file has its own named bar. A failed file keeps its bar where it stopped and says so in words, next to a retry.

```tsx
import { useEffect, useState } from "react"
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
import { Progress } from "@/components/ui/progress"

type File = { name: string; value: number; status: "Done" | "Importing" | "Queued" | "Failed" }

export function Example() {
  const [files, setFiles] = useState<File[]>([
    { name: "customers.csv", value: 100, status: "Done" },
    { name: "orders-2026.csv", value: 60, status: "Importing" },
    { name: "products.csv", value: 0, status: "Queued" },
    { name: "refunds.csv", value: 35, status: "Failed" },
  ])

  const importing = files.some((file) => file.status === "Importing")

  useEffect(() => {
    if (!importing) return
    const id = window.setInterval(() => {
      setFiles((list) =>
        list.map((file) => {
          if (file.status !== "Importing") return file
          const value = Math.min(100, file.value + 10)
          return { ...file, value, status: value === 100 ? "Done" : "Importing" }
        })
      )
    }, 900)
    return () => window.clearInterval(id)
  }, [importing])

  const retry = (name: string) =>
    setFiles((list) => list.map((file) => (file.name === name ? { ...file, status: "Importing" } : file)))

  return (
    <Card className="w-full max-w-[420px]">
      <CardHeader>
        <CardTitle>Import queue</CardTitle>
        <CardDescription>{files.length} files</CardDescription>
      </CardHeader>
      <CardContent>
        <ul className="flex flex-col gap-4">
          {files.map((file) => (
            <li key={file.name} className="flex flex-col gap-2">
              <div className="flex min-h-8 items-center justify-between gap-3 text-sm">
                <span className="font-medium text-foreground">{file.name}</span>
                {file.status === "Failed" ? (
                  <Button variant="plain" size="sm" onClick={() => retry(file.name)}>
                    Failed, retry
                  </Button>
                ) : (
                  <span className="text-text-secondary">{file.status}</span>
                )}
              </div>
              <Progress aria-label={`Import progress for ${file.name}`} value={file.value} valuePosition="right" />
            </li>
          ))}
        </ul>
      </CardContent>
    </Card>
  )
}
```

## For AI agents

`get_component("progress")`

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