Progress
Show known progress toward completion.
Overview
Progress shows task completion with a native progress element. Give it a truthful value and range when the application can measure work, or omit value when completion is genuinely unknown.
Use when
A task has a meaningful known range and current completion value.
Use instead
Use Spinner when progress is indeterminate.
Usage
import { Label, Progress } from "@smoothie-framework/whisk-react";
<Label htmlFor="upload-progress">Uploading documents</Label>
<Progress id="upload-progress" value={62} showLabel valueText="62% uploaded" />Examples
Name the task and show completion
Use a Label to give the native progress bar a name. showLabel displays the current percentage but does not replace the task name.
import { Label, Progress, Stack } from "@smoothie-framework/whisk-react";
<Stack gap={2}>
<Label htmlFor="migration-progress">Migrating workspace</Label>
<Progress
id="migration-progress"
value={62}
showLabel
valueText="62% complete"
/>
</Stack>Describe a custom range
Use valueText when the logical units matter more than the calculated percentage. Whisk/UI converts the logical range to native progress values for you.
import { Label, Progress, Stack } from "@smoothie-framework/whisk-react";
<Stack gap={2}>
<Label htmlFor="upload-progress">Uploading files</Label>
<Progress
id="upload-progress"
min={10}
max={60}
value={35}
showLabel
valueText="35 of 60 files uploaded"
/>
</Stack>Represent unknown completion honestly
Omit value when the task is in progress but the application cannot measure completion. There is no indeterminate prop.
import { Label, Progress, Stack } from "@smoothie-framework/whisk-react";
<Stack gap={2}>
<Label htmlFor="index-progress">Indexing documents</Label>
<Progress id="index-progress" showLabel />
</Stack>Adjust a local visual treatment
Use theme tokens first. Visual props describe the bar only; they do not indicate an error, success, or running application state.
import { Label, Progress, Stack } from "@smoothie-framework/whisk-react";
<Stack gap={2}>
<Label htmlFor="release-progress">Preparing release</Label>
<Progress
id="release-progress"
value={72}
variant="outline"
shape="rounded"
striped
animated
color="accent"
trackColor="surface3"
showLabel
/>
</Stack>Set a vertical range deliberately
Use vertical progress only when the surrounding layout makes the direction clear. The accessible range remains native and unchanged.
import { Label, Progress, Stack } from "@smoothie-framework/whisk-react";
<Stack gap={2}>
<Label htmlFor="storage-progress">Storage used</Label>
<Progress
id="storage-progress"
orientation="vertical"
value={45}
valueText="45% of storage used"
/>
</Stack>Props
Component props
Accessibility
Progress renders a native progress element, so the browser supplies range semantics from value and max. Always name it with a visible Label, aria-label, or aria-labelledby. Do not override role, aria-valuenow, aria-valuemin, or aria-valuemax. showLabel is visual only and is hidden from assistive technology; provide valueText or aria-valuetext when a percentage is not enough, such as 3 of 5 files uploaded. Omit value for indeterminate progress and set value={0} when a known task has not begun. Progress does not announce every change, move focus, run timers, or verify the task state. Keep success, failure, and recovery feedback available elsewhere when users need it.
Content guidance
Name the work and give a meaningful value when a percentage alone is unclear, such as 3 of 5 files uploaded.