Skip to content
Statix Design System

Display

Progress

Rounded bar that shows how far a task or a quota is: a running backup, an upload or mailbox storage.

import { Progress } from '@statix/ui/progress';

Playground

Controls
<Progress />

Examples

Basic

Primary indicator on a bg-2 track.

<script lang="ts">
	import { Progress } from '@statix/ui/progress';
</script>

<Progress value={60} aria-label="Backup progress" class="max-w-md" />

Storage quota

Switch to warning near the limit and destructive at it. Show the numbers next to the bar.

info@yoga-berger.de 4.6 of 5 GB
lena@yoga-berger.de 1.2 of 5 GB
kurse@yoga-berger.de 5 of 5 GB
<script lang="ts">
	import { Progress } from '@statix/ui/progress';

	const mailboxes = [
		{ address: 'info@yoga-berger.de', used: 4.6, variant: 'warning' },
		{ address: 'lena@yoga-berger.de', used: 1.2, variant: 'default' },
		{ address: 'kurse@yoga-berger.de', used: 5, variant: 'destructive' }
	] as const;
</script>

<div class="flex w-full max-w-md flex-col gap-5">
	{#each mailboxes as mailbox (mailbox.address)}
		{@const id = `quota-${mailbox.address.split('@')[0]}`}
		<div class="flex flex-col gap-2">
			<div class="flex justify-between text-small">
				<span {id} class="font-medium text-ink">{mailbox.address}</span>
				<span class="text-muted-foreground">{mailbox.used} of 5 GB</span>
			</div>
			<Progress value={mailbox.used} max={5} variant={mailbox.variant} aria-labelledby={id} />
		</div>
	{/each}
</div>

Sizes

sm (4px), md (8px, default) and lg (12px).

<script lang="ts">
	import { Progress } from '@statix/ui/progress';
</script>

<div class="flex w-full max-w-md flex-col gap-4">
	<Progress value={40} size="sm" aria-label="Small" />
	<Progress value={40} aria-label="Medium" />
	<Progress value={40} size="lg" aria-label="Large" />
</div>

Running task

Bind value to a running backup. The indicator moves with a 300ms ease.

Backing up yoga-berger.de 0%
<script lang="ts">
	import { Progress } from '@statix/ui/progress';
	import { Button } from '@statix/ui/button';

	let value = $state(0);
	let timer: ReturnType<typeof setInterval> | undefined;

	function start() {
		clearInterval(timer);
		value = 0;
		timer = setInterval(() => {
			value = Math.min(100, value + 10);
			if (value === 100) clearInterval(timer);
		}, 400);
	}

	$effect(() => () => clearInterval(timer));
</script>

<div class="flex w-full max-w-md flex-col gap-3">
	<div class="flex justify-between text-small">
		<span id="backup-label" class="font-medium text-ink">Backing up yoga-berger.de</span>
		<span class="text-muted-foreground">{value}%</span>
	</div>
	<Progress
		{value}
		variant={value === 100 ? 'success' : 'default'}
		aria-labelledby="backup-label"
	/>
	<Button variant="outline" size="sm" class="self-start" onclick={start}>Start backup</Button>
</div>

Guidelines

Do

  • Put a label and the numbers next to the bar: "4.6 of 5 GB".
  • Use status variants for quotas so the colour shows how close the limit is.

Don't

  • Don’t use a progress bar when you cannot tell how far along the task is. Use a spinner.
  • Don’t use the colour alone to warn. Say it in text as well.

Accessibility

  • Renders role="progressbar" with aria-valuenow, aria-valuemin and aria-valuemax from bits-ui.
  • Give it a name with aria-label or aria-labelledby pointing at the visible label.
  • Pass value={null} for an unknown amount. The bar then fills and pulses, and aria-valuenow is removed.

API reference

Progress

renders <div role="progressbar"> and accepts its attributes
PropTypeDefault
value number | null

Current value. null means indeterminate.

–
max number

Maximum value.

100
min number

Minimum value.

0
variant 'default' | 'success' | 'warning' | 'destructive'

Indicator colour.

'default'
size 'sm' | 'md' | 'lg'

Track height: 4, 8 or 12px.

'md'
ref bindHTMLDivElement | null

The rendered element.

–
class ClassValue

Merged with the track classes; yours win.

–
Data attributeMeaning
data-slot="progress"The track.
data-slot="progress-indicator"The moving bar inside.
data-stateloading, complete or indeterminate (from bits-ui).
data-variantThe current variant.

progressVariants

tailwind-variants function with track and indicator slots.