# Progress

> A bar that shows how far a measurable task has gone, such as an upload or usage against a limit, with a label and its value.

Source: https://raft-design.botiverse.build/components/progress. Generated from the current release; where it differs from what you remember, this page is right.

A progress bar shows how far something with a known percentage has gone: an upload, a file being processed, usage against a quota. Next to it, a label says what it is and how far it has got. Which loading indicator fits which wait is in [Choosing a component](https://raft-design.botiverse.build/components.md#waiting).

```tsx
import {
  Progress,
  ProgressHeader,
  ProgressIndicator,
  ProgressLabel,
  ProgressTrack,
  ProgressValue,
} from "@botiverse/raft-ui";

export function ProgressPreviewContent() {
  return (
    <div className="w-full max-w-sm">
      <Progress value={64} variant="primary">
        <ProgressHeader>
          <ProgressLabel>Uploading transcript</ProgressLabel>
          <ProgressValue />
        </ProgressHeader>
        <ProgressTrack>
          <ProgressIndicator />
        </ProgressTrack>
      </Progress>
    </div>
  );
}
```

## When to use

| Situation                              | Use                                                  |
| -------------------------------------- | ---------------------------------------------------- |
| The percentage is known                | Progress                                             |
| The duration is unknown                | [Spinner](https://raft-design.botiverse.build/components/spinner.md), not a progress bar |
| The layout of what is loading is known | [Skeleton](https://raft-design.botiverse.build/components/skeleton.md)                  |

## Anatomy

- `Progress`: the root; takes the `value`. Required.
- `ProgressHeader`: an optional row above the track, holding `ProgressLabel` (what it is) and `ProgressValue` (how far, in Space Mono).
- `ProgressTrack`: the `fill-muted` track. Required.
- `ProgressIndicator`: the fill, a sticker with an ink edge. Required.

## Variants

| Variant                           | Use for                                                              |
| --------------------------------- | -------------------------------------------------------------------- |
| The default (`variant="primary"`) | Progress of any kind: an `info` fill                                 |
| `variant="warning"`               | Usage at 90% of a limit or more                                      |
| Complete                          | When `value` reaches the maximum the fill turns `success` on its own |

- Don't use `variant="danger"`: reaching a limit interrupts, it isn't irreversible ([Color](https://raft-design.botiverse.build/foundations/color.md#meanings-of-color)).
- `information` and `accent` are the same as the default. Use the default.

```tsx
import {
  Progress,
  ProgressHeader,
  ProgressIndicator,
  ProgressLabel,
  ProgressTrack,
  ProgressValue,
} from "@botiverse/raft-ui";

export function EmbeddedProgressComposition() {
  return (
    <div className="w-full max-w-sm stack-y-2 rounded-md border border-line-hairline p-3">
      <div className="flex items-center justify-between gap-4 text-sm">
        <span className="min-w-0 truncate">example-document.txt</span>
        <span className="shrink-0 text-foreground-muted">Processing</span>
      </div>
      <Progress value={48} size="sm" variant="information">
        <ProgressHeader>
          <ProgressLabel>Processing example-document.txt</ProgressLabel>
          <ProgressValue />
        </ProgressHeader>
        <ProgressTrack>
          <ProgressIndicator />
        </ProgressTrack>
      </Progress>
    </div>
  );
}
```

## States

- Don't show a bar whose percentage can't be computed. Use a [Spinner](https://raft-design.botiverse.build/components/spinner.md) instead of a fake or indeterminate bar.

## Content

- Name what is in progress in `ProgressLabel`: "Uploading design-crop.png", "Agent hours this month".
- Show how far it has got in `ProgressValue`, as a percentage or as an amount out of the limit.

## Accessibility

Progress wraps Base UI's Progress, which gives it `role="progressbar"` and its value.

- `ProgressLabel` gives the bar its accessible name. Without a visible label, pass `aria-label` to `Progress`.
- Keep `ProgressLabel` even when you leave out `ProgressValue`.

## Rules

- Put a bar inside a file card, thumbnail or other rounded container on its own thin track, never along its edge ([Shape](https://raft-design.botiverse.build/foundations/shape.md#nothing-on-the-edge-of-a-rounded-container)).

## API

### Progress

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` |  |
| `variant` | `"primary" \| "accent" \| "warning" \| "danger" \| "information" \| "success"` | `"primary"` |  |
| `aria-valuetext` | `string` |  | A string value that provides a user-friendly name for `aria-valuenow`, the current value of the progress bar. |
| `format` | `Intl.NumberFormatOptions` |  | Options to format the value. |
| `getAriaValueText` | `(formattedValue: string, value: number \| null) => string` |  | Accepts a function which returns a string value that provides a human-readable text alternative for the current value of the progress bar. |
| `locale` | `string \| Intl.Locale \| readonly (string \| Intl.Locale)[]` |  | The locale used by `Intl.NumberFormat` when formatting the value. Defaults to the user's runtime locale. |
| `max` | `number` | `100` | The maximum value. |
| `min` | `number` | `0` | The minimum value. |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |
| `value` (required) | `number` |  | The current value. The component is indeterminate when value is `null`. |

Also takes the attributes of its element.

### ProgressHeader

Also takes the attributes of its element.

### ProgressIndicator

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### ProgressLabel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### ProgressTrack

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### ProgressValue

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `(formattedValue: string \| null, value: number \| null) => React.ReactNode` |  |  |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.