---
title: "Progress"
description: "Shows how much of a task is complete."
category: "Feedback & Status"
slug: progress
url: /components/progress
since: "0.2.0"
status: "stable"
---

# Progress

Shows how much of a task is complete.

## Import

```svelte
import { Progress } from '@elluzion/iv-ui';
```

## Preview

A bar bound to a value on a 0–100 scale.

```svelte
<script lang="ts">
	import { Progress } from '@elluzion/iv-ui';
</script>

<div class="field-row">
	<Progress value={42} label="Upload" />
</div>

<style>
	.field-row {
		width: 100%;
		max-width: 380px;
	}
</style>
```

## Usage

- Set `max` when the scale is not 0–100; the percentage is derived.
- `indeterminate` hides the value and animates the track.
- `label` names the bar; `showValue` prints the percentage.

## Examples

### Labeled

`label` and `showValue` add a header above the track.

```svelte
<script lang="ts">
	import { Progress } from '@elluzion/iv-ui';

	let completed = $state(68);
</script>

<div class="stack">
	<Progress value={completed} label="Migration" showValue />
	<div class="row">
		<button class="step" onclick={() => (completed = Math.max(0, completed - 10))}>−10</button>
		<button class="step" onclick={() => (completed = Math.min(100, completed + 10))}>+10</button>
	</div>
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		gap: var(--iv_spacing-md);
		width: 100%;
		max-width: 380px;
	}

	.row {
		display: flex;
		gap: var(--iv_spacing-sm);
	}

	.step {
		padding: var(--iv_spacing-2xs) var(--iv_spacing-sm);
		border: 1px solid var(--iv_border);
		border-radius: var(--iv_radius-sm);
		background: var(--iv_surface-raised);
		color: var(--iv_foreground);
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		cursor: pointer;
	}
</style>
```

### Indeterminate

Use when progress is unknown but the work is running.

```svelte
<script lang="ts">
	import { Progress } from '@elluzion/iv-ui';
</script>

<div class="field-row">
	<Progress indeterminate label="Waiting for the runner" />
</div>

<style>
	.field-row {
		width: 100%;
		max-width: 380px;
	}
</style>
```

### Sizes

`sm` for dense rows and `md` for page-level progress.

```svelte
<script lang="ts">
	import { Progress } from '@elluzion/iv-ui';
</script>

<div class="stack">
	<Progress value={30} size="sm" label="Small" showValue />
	<Progress value={30} label="Medium" showValue />
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		gap: var(--iv_spacing-lg);
		width: 100%;
		max-width: 380px;
	}
</style>
```

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | `0` | Current progress value. |
| `max` | `number` | `100` | Value that represents completion. |
| `indeterminate` | `boolean` | `false` | Renders an animated unknown-progress state. |
| `label` | `string` | `''` | Visible label and accessible name. |
| `showValue` | `boolean` | `false` | Shows the percentage at the end of the track. |
| `size` | `'sm' \| 'md'` | `'md'` | Track thickness. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |

`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.

### Tokens used

`--iv_cursor` · `--iv_ease-in-out` · `--iv_font-mono` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_progress-h-md` · `--iv_progress-h-sm` · `--iv_radius-sm` · `--iv_spacing-sm` · `--iv_surface-elevated` · `--iv_text-label` · `--iv_text-sm` · `--iv_transition-base` · `--iv_weight-medium`

See the [token reference](/foundations/tokens.md) for values.

### CSS hooks

`.iv-fill` · `.iv-fill-wrap` · `.iv-indeterminate` · `.iv-label` · `.iv-progress` · `.iv-progress-header` · `.iv-sm` · `.iv-track` · `.iv-value`

## Accessibility

| Keys | Action |
| --- | --- |
| `Escape` | Not applicable; the bar is read-only. |

- The bar uses `role="progressbar"` with `aria-valuemin`, `aria-valuemax`, and `aria-valuenow`.
- Indeterminate bars omit the value and use `aria-valuetext="Indeterminate"`.
- `label` becomes the accessible name through `aria-labelledby`.

## Related

- [LoadingSpinner](/components/loading-spinner.md)
- [Skeleton](/components/skeleton.md)
- [Slider](/components/slider.md)
- [Alert](/components/alert.md)