---
title: Progress
description: Show measurable or indeterminate task progress.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Progress

> Show measurable or indeterminate task progress.

## Anatomy

```text
Progress [component; slot=root]
├── label [slot]
├── value [slot]
└── track [slot]
    └── indicator [slot]
```

## Usage

Use Progress for measurable task completion or for work whose end is not yet known. Choose a
determinate value only when it represents real progress. For a loading placeholder of content
structure, use [Skeleton](https://moraine.subf.dev/components/skeleton.md).

```tsx
import { Progress } from 'moraine'

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

### Progress models

Pass a numeric `value` from `0` to `max` for determinate progress; `max` defaults to `100`, and a
`value` outside the range is clamped. Omit `value` for indeterminate progress, which sets no
`aria-valuenow` and takes its `aria-valuetext` from the `progress.indeterminate` message. Use
`animation` (`carousel`, `reverse`, `swing`, or `elastic`) to change the indeterminate motion.

```tsx
<Progress value={65} aria-label="Uploading design.fig" />
<Progress aria-label="Scanning for malware" />
```

### Label and value

Supply `aria-label` or a labelling relationship when the surrounding context does not name the
operation. `label` fills the label slot, and a string `label` is also the default `aria-label`. An
explicit `aria-label` takes precedence. `valueLabel` shows the percentage in the value slot; pass a
formatter to customize both the displayed text and `aria-valuetext`. Without `valueLabel`,
`aria-valuetext` is still the formatted percentage. Indeterminate progress keeps the label and hides
the value.

```tsx
<Progress value={82} label="Downloading installation bundle" valueLabel aria-label="Download" />
<Progress value={40} valueLabel={({ percent }) => `${percent}% complete`} aria-label="Export" />
```

### Orientation

Progress fills left to right by default. Set `orientation="vertical"` for a bar that fills from the
bottom, for example a battery or level meter. The vertical bar grows to its container height with a
minimum of 9rem.

```tsx
<Progress value={72} orientation="vertical" aria-label="Battery level" />
```

### Number format

`formatOptions` accepts `Intl.NumberFormat` options and formats the displayed value and
`aria-valuetext` with the provider locale. A `percent` style formats the completed fraction; other
styles format `value`. Without `formatOptions`, the text is the percentage rounded to two decimals.
A `valueLabel` formatter takes precedence.

```tsx
<Progress value={3} max={4} valueLabel formatOptions={{ style: 'percent' }} aria-label="Setup" />
<Progress value={42} valueLabel formatOptions={{ style: 'unit', unit: 'megabyte' }} aria-label="Upload" />
```

## Examples

### Upload a file or wait on a scan

Use a determinate value for known bytes. Omit `value` while a scanner has no trustworthy percentage.

```tsx
import { Progress } from 'moraine'

export function Models() {
  return (
    <div class="max-w-md w-full space-y-4">
      <Progress label="Uploading design.fig" value={65} aria-label="Uploading design.fig" />
      <Progress label="Scanning for malware" aria-label="Scanning for malware" />
    </div>
  )
}
```

### Announce a bundle download

Set `label` and `valueLabel` when the operation name and percentage should appear with the bar.
Keep `aria-label` as the accessible name.

```tsx
import { Progress } from 'moraine'

export function Semantics() {
  return (
    <div class="max-w-md w-full">
      <Progress
        label="Downloading installation bundle"
        value={82}
        valueLabel
        aria-label="Downloading installation bundle"
      />
    </div>
  )
}
```

### Show horizontal and vertical meters

Use `orientation="vertical"` for level meters that fill from the bottom.

```tsx
import { Progress } from 'moraine'

export function Orientation() {
  return (
    <div class="flex gap-8 items-end">
      <div class="max-w-md w-full">
        <Progress
          label="Disk usage"
          value={72}
          valueLabel
          orientation="horizontal"
          aria-label="Disk usage"
        />
      </div>
      <Progress value={72} orientation="vertical" aria-label="Battery level" />
    </div>
  )
}
```

## API Reference

### Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-indeterminate` | `progress`, `progress-indicator` | Present when the checkbox or progress state is indeterminate. |
| `data-progress` | `progress`, `progress-indicator` | Stores whether determinate progress is loading or complete. |

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| animation | 'carousel' \| 'reverse' \| 'swing' \| 'elastic' \| undefined | 'carousel' | Visual animation of the component. |
| formatOptions | Intl.NumberFormatOptions \| undefined | — | `Intl.NumberFormat` options for the displayed value, using the provider locale. A<br>`percent` style formats the completed fraction; other styles format `value`.<br>Defaults to the percentage rounded to 2 decimal places. |
| label | JSX.Element \| undefined | — | Content for the label slot. Also used as the default `aria-label` when it is a string; an<br>explicit `aria-label` takes precedence. |
| max | number \| undefined | 100 | The value that counts as complete. A negative or non-finite number falls back to `100`. |
| orientation | 'horizontal' \| 'vertical' \| undefined | 'horizontal' | Visual layout direction. |
| size | 'sm' \| 'md' \| 'lg' \| undefined | 'md' | Visual size of the component. |
| translations | Translations \| undefined | — | Localized message overrides for this progress instance, such as the `aria-valuetext` announced while indeterminate. |
| value | number \| undefined | undefined | The current value, from `0` to `max`; values outside that range are clamped. Leave it `undefined`<br>(or non-finite) for indeterminate progress, which sets no `aria-valuenow`. |
| valueLabel | boolean \| ((props: { percent: number; value: number; max: number }) => string) \| undefined | false | Whether to show the value slot for determinate progress, or a formatter for it.<br>The formatter receives the clamped `value`, `max` and `percent` (`0`-`100`, rounded to 2 decimals)<br>and returns the text; the result also supplies `aria-valuetext`. Nothing is shown while indeterminate. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |

**`valueLabel` example**

```tsx
import { Progress } from 'moraine'

<Progress
  value={3}
  max={8}
  label="Files"
  valueLabel={({ value, max }) => `${value} of ${max}`}
/>
```
