Skip to content
Browse documentation
whisk/ui

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

62% uploaded
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.

62% complete
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.

35 of 60 files uploaded
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.

Loading...
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.

72%
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.

45% of storage used
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

PropTypeDefaultDescription
valuenumber | undefinedundefinedSet a finite current value. Values outside min through max clamp to that range; omit value for indeterminate progress.
min | maxnumber0 | 100Set the logical range. Both must be finite and max must be greater than min.
showLabelbooleanfalseShow the computed percentage or valueText beside the bar. The visible text is hidden from assistive technology to avoid duplicate output.
valueText | aria-valuetextstringcomputed valueDescribe the current amount in meaningful units, such as 3 of 5 files uploaded. aria-valuetext takes precedence when both are supplied.
size | variant | shapexs | sm | md | lg | subtle | outline | square | rounded | fullmd | subtle | fullSet the progress bar's visual density, treatment, and end shape.
orientation | striped | animatedhorizontal | vertical | boolean | booleanhorizontal | false | falseChange the axis and add a striped or animated visual treatment. These props do not change the task state.
color | trackColorColorToken | CSS named colortheme defaultsSet the completed range and track colors with theme tokens or CSS named colors.
aria-label | aria-labelledby | native progress attributesnative attributesnoneName the progress bar with a native label or ARIA attribute. role and ARIA range values are derived from the native element and cannot be overridden.

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.