---
title: Progress
description: Progress shows the completion progress of a task in shape of a bar, displayed as a progress bar..
thumbnail:
  image: /previews/components/core/progress.jpeg
  video: /previews/components/core/progress.mp4
links:
  - label: Aria docs
    href: https://react-spectrum.adobe.com/react-aria/ProgressBar.html
  - label: Aria API Reference
    href: https://react-spectrum.adobe.com/react-aria/ProgressBar.html#props
  - label: Report an issue
    href: https://github.com/mehdibha/dotUI/issues/new/choose
  - label: Edit this page
    href: https://github.com/mehdibha/dotUI/tree/main/content/components/feedback/progress.mdx?plain=1
---

<ComponentPreview
  name="core/progress-default"
  preview={`<Progress value={75} />`}
/>

## Installation

<Tabs items={["CLI", "Manual"]}>
  <Tab value="CLI">
  
  ```package-install
npx dotui-cli@latest add progress
```

  </Tab>
  <Tab value="manual">
  
    <Steps>
      <Step>Install the following dependencies:</Step>

    ```package-install
    react-aria-components
    ```

      <Step>Copy and paste the following code into your project.</Step>
      <ComponentSource name="core/progress" />
      <Step>Update the import paths to match your project setup.</Step>
    </Steps>

  </Tab>
</Tabs>

## Usage

Use `Progress` to show the completion progress of a task. It can represent either determinate or indeterminate progress.

### Best pratices

When possible, use a determinate progress indicator.<br/>
An indeterminate progress indicator shows that a process is occurring, but it doesn't help people estimate how long a task will take.<br/>
A determinate progress indicator can help people decide whether to do something else while waiting for the task to complete, restart the task at a different time, or abandon the task.

## Options

### Variant

Use the `variant` prop to control the visual style of the `Progress`. The default variant is `"default"`.

<ComponentPreview
  name="core/progress-variants"
  preview={`<Progress variant="default" />
<Progress variant="success" />
<Progress variant="accent" />
<Progress variant="danger" />
<Progress variant="warning" />`}
/>

### Size

Use the `size` prop to control the size of the `Progress`. The default variant is `"md"`.

<ComponentPreview
  name="core/progress-sizes"
  preview={`<Progress size="sm" />
<Progress size="md" />
<Progress size="lg" />`}
/>

### Label

A visual label can be provided for the `Progress` using the label prop, or a hidden label using `aria-label` prop.

<ComponentPreview
  name="core/progress-label"
  preview={`<Progress aria-label="loading" />
<Progress label="loading..." />`}
/>

### Value label

Set the `showValueLabel` prop to `true` to display the current value of the progress bar.

<ComponentPreview
  name="core/progress-value-label"
  preview={`<Progress label="Loading" showValueLabel value={75} />`}
/>

### Format options

Values are formatted as a percentage by default, but this can be modified by using the `formatOptions` prop to specify a different format.

<ComponentPreview
  name="core/progress-format-options"
  preview={`<Progress
    label="Sending…"
    showValueLabel
    formatOptions={{ style: "currency", currency: "JPY" }}
    value={60}
  />`}
/>

### Custom value label

The `valueLabel` prop allows the formatted value to be replaced with a custom string.

<ComponentPreview
  name="core/progress-custom-value-label"
  preview={`<Progress
    label="Feeding…"
    showValueLabel
    valueLabel="30 of 100 dogs"
    value={30}
  />`}
/>

### Indeterminate

The `isIndeterminate` prop can be used to represent an interdeterminate operation.

<ComponentPreview
  name="core/progress-indeterminate"
  preview={`<Progress isIndeterminate aria-label="Loading" />`}
/>

### Duration

Use the duration prop to indicate an approximate duration of an indeterminate task. Once the duration times out, the progress bar will start an indeterminate animation.

<ComponentPreview
  name="core/progress-duration"
  preview={`<Progress duration="30s" />`}
/>

### Min and max values

A custom value scale can be used by setting the `minValue` and `maxValue` props.

<ComponentPreview
  name="core/progress-min-max-values"
  preview={`<Progress
    aria-label="Min and max values"
    minValue={50}
    maxValue={150}
    value={100}
  />`}
/>

## Examples

### Composition

If you need to customize things further, you can drop down to the composition level.

<ComponentPreview
  name="core/progress-composition"
  preview={`<ProgressRoot value={50} className="flex-row items-center gap-4">
    <Label>Progress</Label>
    <ProgressIndicator />
    <ProgressValueLabel />
  </ProgressRoot>`}
/>

### Custom color

<ComponentPreview
  name="core/progress-custom-color"
  preview={`<Progress
    value={75}
    aria-label="Custom color"
    classNames={{
      indicator: "bg-slate-300 dark:bg-slate-800",
      filler: "bg-slate-800 dark:bg-slate-300",
    }}
  />`}
/>

### Toolbar

<ComponentPreview name="core/progress-toolbar" preview={``} />

## API Reference

| Prop              | Type                                                                                                     | Default              | Description                                                                                                 |
| ----------------- | -------------------------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------- |
| `variant`         | `"default" \| "primary" \| "danger" \| "success" \| "warning"`                                           | `"default"`          | The visual style of the progress indicator.                                                                 |
| `size`            | `"sm" \| "md" \| "lg"`                                                                                   | `"md"`               | The size of the progress indicator                                                                          |
| `isIndeterminate` | `boolean`                                                                                                | -                    | Whether presentation is indeterminate when progress isn't known.                                            |
| `formatOptions`   | `Intl.NumberFormatOptions`                                                                               | `{style: 'percent'}` | The display format of the value label.                                                                      |
| `valueLabel`      | `ReactNode`                                                                                              | -                    | The content to display as the value's label (e.g. 1 of 4).                                                  |
| `showValueLabel`  | `boolean`                                                                                                | `false`              | Whether the value's label is displayed.                                                                     |
| `value`           | `number`                                                                                                 | `0`                  | The current value (controlled).                                                                             |
| `minValue`        | `number`                                                                                                 | `0`                  | The smallest value allowed for the input.                                                                   |
| `maxValue`        | `number`                                                                                                 | `100`                | The largest value allowed for the input.                                                                    |
| `children`        | `ReactNode \| (values: ProgressBarRenderProps & {defaultChildren: ReactNode \| undefined}) => ReactNode` | -                    | The children of the component. A function may be provided to alter the children based on component state.   |
| `className`       | `string`                                                                                                 | -                    | The CSS className for the element.                                                                          |
| `style`           | `CSSProperties \| (values: ProgressBarRenderProps & {defaultStyle: CSSProperties}) => CSSProperties`     | -                    | The inline style for the element. A function may be provided to compute the style based on component state. |

| CSS Selector            | Description                                |
| ----------------------- | ------------------------------------------ |
| `[aria-valuetext]`      | A formatted version of the value.          |
| `:not([aria-valuenow])` | Whether the progress bar is indeterminate. |
