# Progress

> A determinate or indeterminate progress bar.

URL: https://apogee.avaui.dev/docs/progress
Last updated: 2026-10-15

A determinate or indeterminate progress bar.

Last updated October 15, 2026

```astro
<Progress value={60} label="Upload progress" />
```

For a ring or a gauge see [Circular progress](https://apogee.avaui.dev/docs/circular-progress).

## Add

```sh
npx @ava-ui/apogee add progress
```

No Apogee component dependencies, no icons. Zero JS.

## Usage

```astro
---
import Progress from '@/components/apogee/Progress/Progress.astro'
---
<Progress value={40} max={100} label="Profile completeness" />
```

## API

`@composable` — exposed to Content Editors in AVA. Any other attribute passes through to the root `<div role="progressbar">`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | `0` | Current value, `0`–`max`. Ignored visually when `indeterminate`. |
| `min` | `number` | `0` | Lower bound. |
| `max` | `number` | `100` | Maximum value. |
| `label` | `string` | — | Accessible label (`aria-label`) — there’s no visible text otherwise. |
| `indeterminate` | `boolean` | `false` | Shows a sliding animated fill instead of a value-based width; drops `aria-valuemin` / `aria-valuemax` / `aria-valuenow`. |
| `size` | `'small' \| 'medium'` | `'medium'` | Bar thickness: 4 / 8px. |
| `color` | `'primary' \| 'neutral' \| 'critical' \| 'positive' \| 'warning'` | `'primary'` | Hue of the fill. |
| `labelPosition` | `'none' \| 'end' \| 'bottom' \| 'floating'` | `'none'` | Where the value text shows: after the bar, under it, or in a chip that floats above the fill. |
| `format` | `string` | `'{percent}%'` | Value text template; `{value}`, `{percent}` and `{max}` are replaced. |
| `class` | `string` | — | Extra classes on the root wrapper, merged last. |

## Value labels

Every `labelPosition`, with a `format`:

```astro
<Progress value={60} label="Upload" labelPosition="end" />
<Progress value={60} label="Upload" labelPosition="bottom" format="{value} of {max} files" />
<Progress value={60} label="Upload" labelPosition="floating" />
```

## Sizes

```astro
<Progress value={40} size="small" label="Small" />
<Progress value={40} size="medium" label="Medium" />
```

## Colours

```astro
<Progress value={60} color="primary" label="Primary" />
<Progress value={60} color="neutral" label="Neutral" />
<Progress value={60} color="critical" label="Critical" />
<Progress value={60} color="positive" label="Positive" />
<Progress value={60} color="warning" label="Warning" />
```

## States

Determinate, at a few values:

```astro
<Progress value={0} label="0%" />
<Progress value={40} label="40%" />
<Progress value={100} label="100%" />
```

Indeterminate — a 40%-wide fill slides on a loop:

```astro
<Progress indeterminate label="Loading" />
```

## Examples

A step counter using a non-percentage `max`:

```astro
<Progress value={2} max={4} label="Step 2 of 4" />
```

## Accessibility

-   `role="progressbar"` with `aria-valuemin` / `aria-valuemax` / `aria-valuenow`; all three are omitted when `indeterminate`, matching the ARIA spec for an indeterminate progress meter.
-   `label` sets `aria-label` — always pass one; the bar has no visible text.
-   The indeterminate slide respects `prefers-reduced-motion`: its 1.2s loop slows to 3s. The determinate fill’s width transition has no separate reduced-motion guard.

## Tokens

| Token | Used for |
| --- | --- |
| `--background-neutral-faded` | Track background |
| `--background-primary` | Fill |
| `--background-inverted` / `--on-inverted` | Floating value chip |
| `--duration-slow` | Determinate fill transition duration |
| `--ease-standard` | Transition / animation easing |

## Do / Don’t

-   **Do** always pass `label` — the bar has no visible text of its own.
-   **Do** use `indeterminate` only when a percentage genuinely can’t be computed; switch to determinate the moment you can.
-   **Don’t** write the value into the track yourself; use `labelPosition`, which keeps the text out of the fill.
-   **Don’t** animate `value` faster than users can perceive as real progress rather than decoration.

## Content

-   `label` states what’s progressing (“Uploading…”, “Step 2 of 4”), not the percentage — the number is already conveyed through ARIA.

## Related

[

ProgressIndicatorStep N of M as a row of segments, for onboarding flows, wizards and carousels. Zero JS.

](https://apogee.avaui.dev/docs/progress-indicator)[

MeterA native meter gauge for a measurement in a known range, like disk usage or a score.

](https://apogee.avaui.dev/docs/meter)[

SpinnerA spinning loading indicator. Zero JS.

](https://apogee.avaui.dev/docs/spinner)[

LoaderTextText with a moving shimmer while something loads, crossfading to a done label when it finishes.

](https://apogee.avaui.dev/docs/loader-text)