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
<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| Prop | Type | Default |
|---|---|---|
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 bind | HTMLDivElement | null The rendered element. | – |
class | ClassValue Merged with the track classes; yours win. | – |
| Data attribute | Meaning |
|---|---|
data-slot="progress" | The track. |
data-slot="progress-indicator" | The moving bar inside. |
data-state | loading, complete or indeterminate (from bits-ui). |
data-variant | The current variant. |
progressVariants
tailwind-variants function with track and indicator slots.