---
id: "packages/active-ui/progress"
title: "Progress"
description: "How far a task has come, as a bar with its label and value, or as an ongoing task of unknown length."
url: "/packages/active-ui/progress"
locale: "en"
revision: "609a41b61a418bd6"
---

# Progress

A progress bar shows how far a task has come: an upload, an import, a batch. With a value it shows
the share done; with `value={null}` it shows that the task runs without a known end. It is built
on Base UI's progress. For a short wait without a measure, a [spinner](/packages/active-ui/spinner)
is enough; for steps the reader takes, use a stepper.

**Example: A known amount and an unknown one**

Client: Runs entirely in your browser. Source: `examples/ui/progress.tsx`.

```tsx
// apps/docs/examples/ui/progress.tsx
'use client';

import {useEffect, useState} from 'react';

import {Button} from '@workspace/active-ui/components/primitives/button';
import {
  Progress,
  ProgressLabel,
  ProgressValue,
} from '@workspace/active-ui/components/primitives/progress';

/**
 * How far a task has come: an upload that advances (simulated with a
 * timer), with its label and its value as text, and a task of unknown
 * length (`value={null}`).
 */
export default function ProgressExample() {
  const [value, setValue] = useState(0);
  const [running, setRunning] = useState(false);
  useEffect(() => {
    if (!running) return;
    const timer = window.setInterval(() => {
      setValue((current) => {
        if (current >= 100) {
          setRunning(false);
          return 100;
        }
        return current + 10;
      });
    }, 300);
    return () => window.clearInterval(timer);
  }, [running]);
  return (
    <div className="flex w-full max-w-sm flex-col gap-8">
      <div className="flex flex-col gap-3">
        <Progress value={value}>
          <ProgressLabel>Uploading participants.csv</ProgressLabel>
          <ProgressValue />
        </Progress>
        <Button
          variant="outline"
          size="sm"
          className="self-start"
          disabled={running}
          onClick={() => {
            setValue(0);
            setRunning(true);
          }}
        >
          {value === 100 ? 'Upload again' : 'Start the upload'}
        </Button>
      </div>
      <Progress value={null}>
        <ProgressLabel>Checking the addresses</ProgressLabel>
      </Progress>
    </div>
  );
}
```

## Usage

```tsx
import {
  Progress,
  ProgressLabel,
  ProgressValue,
} from '@workspace/active-ui/components/primitives/progress';

<Progress value={60}>
  <ProgressLabel>Uploading participants.csv</ProgressLabel>
  <ProgressValue />
</Progress>;
```

## Anatomy

- `Progress`: the bar and its state. `value` (a number between `min` and `max`, default `0` to
  `100`, or `null` for unknown), `format` and `locale` for the value text.
- `ProgressLabel` and `ProgressValue`: the label and the value as text, above the bar. The value is
  formatted with `Intl.NumberFormat`.
- `ProgressTrack` and `ProgressIndicator`: the bar itself, which `Progress` renders.

## What your application provides

- The value as the task advances, and a label that says what is in progress.
- `locale`, so the value text follows your presentation rather than the browser's language.
- What happens when the task ends: replace the bar with the result.

## Accessibility

The bar is a `role="progressbar"` named by its label, with its value (`aria-valuenow`) and the
value text; without a value it is reported as busy. A screen reader reads the value when it reaches
the bar; announce the end of a long task separately, for example with a toast.

## API

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `number \| null` | yes | The current value. The component is indeterminate when value is `null`. |
| `aria-valuetext` | `string` | no | A string value that provides a user-friendly name for `aria-valuenow`, the current value of the progress bar. |
| `format` | `Intl.NumberFormatOptions` | no | Options to format the value. |
| `getAriaValueText` | `((formattedValue: string, value: number \| null) => string)` | no | Accepts a function which returns a string value that provides a human-readable text alternative for the current value of the progress bar. |
| `locale` | `Intl.LocalesArgument` | no | The locale used by `Intl.NumberFormat` when formatting the value. Defaults to the user's runtime locale. |
| `max` | `number` | no | The maximum value. |
| `min` | `number` | no | The minimum value. |
| `render` | `ComponentRenderFn<HTMLProps, ProgressRootState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` | no | Allows you to replace the component's HTML element with a different tag, or compose it with another component.  Accepts a `ReactElement` or a function that returns the element to render. |

### Other parts

**ProgressTrack**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `render` | `ComponentRenderFn<HTMLProps, ProgressTrackState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` | no | Allows you to replace the component's HTML element with a different tag, or compose it with another component.  Accepts a `ReactElement` or a function that returns the element to render. |

**ProgressIndicator**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `render` | `ComponentRenderFn<HTMLProps, ProgressIndicatorState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` | no | Allows you to replace the component's HTML element with a different tag, or compose it with another component.  Accepts a `ReactElement` or a function that returns the element to render. |

**ProgressLabel**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `render` | `ComponentRenderFn<HTMLProps, ProgressLabelState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` | no | Allows you to replace the component's HTML element with a different tag, or compose it with another component.  Accepts a `ReactElement` or a function that returns the element to render. |

**ProgressValue**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `((formattedValue: string \| null, value: number \| null) => ReactNode) \| null` | no |  |
| `render` | `ComponentRenderFn<HTMLProps, ProgressValueState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` | no | Allows you to replace the component's HTML element with a different tag, or compose it with another component.  Accepts a `ReactElement` or a function that returns the element to render. |

> [!NOTE]
> **Based on shadcn/ui**
>
> This page adapts the Progress documentation of shadcn/ui (MIT licence) to this
> package; see [Third-party notices](/third-party-notices).