Progress bar

The progress bar is a visual indicator that shows how much of a task or process has been completed, giving users immediate feedback.

Usage

Code

Accessibility

20% of 100%

Done

Preparing download

  <sl-progress-bar value="20" label="File download">
    20% of 100%
  </sl-progress-bar>
  <sl-progress-bar value="50" label="File download" variant="success">
    Done
  </sl-progress-bar>
  <sl-progress-bar indeterminate label="File download">
    Preparing download
  </sl-progress-bar>

When to use

Long operations

A progress bar is essential for tasks that can take a considerable amount of time to complete or have unpredictable durations. It helps users stay informed about the ongoing status of the process.

File uploads/downloads

A progress bar is used to visually indicate the progression of system operations like downloading and uploading files. It provides users with real-time feedback on the status of these processes.

A progress bar is suitable when the progress of a task can be quantitatively measured, such as using percentages. For instance, it's effective for showing teachers the percentage completion of their students' assignments.

When not to use

Expanded information

When the loading time is anticipated to display extensive information, opt for skeleton states instead of a progress bar.

Short actions

If a process completes quickly, typically in less than 5 seconds, it's better to use a spinner instead of implementing a progress bar.

Anatomy

Item	Name	Description	Optional
1	Label	Text describing the process referenced by the progress bar. Can be visually hidden but must be defined for accessibility purposes.	yes
2	Hint	Assistive text providing additional information about the ongoing process. For determinate progress bars, it typically displays progression as a percentage, fraction, ratio, or numeric value.	no
3	Track	The static area that the bar indicator moves on top of and acts as a fixed visual reference of what the total length and duration of the process could be.	no
4	Bar indicator	Indicates how much the process has progressed.	yes
5	Status icon	Indicates the state of the progress bar.	yes

Figma Options

With these options, you can tweak the appearance of the progress bar in Figma. They are available in the Design Panel so you can compose the progress bar to exactly fit the user experience need for the use case you are working on.

Item	Options	Description
State	`default` `success` `error` `warning`	To indicate the state of the progress bar.
Progress	`0%` `25%` `50%` `75%` `100%` `inderterminate`	To visualise the progress.
Label	`boolean`	To show the label on top of the progress bar.
Hint	`value`	To enter the value of the hint.

Uploaded 60% of 100%

File uploaded succesfully

File size is too big

Uploaded an invalid file type

Please wait

  <sl-progress-bar value="60" label="File upload">
    Uploaded 60% of 100%
  </sl-progress-bar>
  <sl-progress-bar value="100" label="File upload" variant="success">
    File uploaded succesfully
  </sl-progress-bar>
  <sl-progress-bar value="30" label="File upload" variant="warning">
    File size is too big
  </sl-progress-bar>
  <sl-progress-bar value="100" label="File upload" variant="error">
    Uploaded an invalid file type
  </sl-progress-bar>
  <sl-progress-bar indeterminate label="Generating report">
    Please wait
  </sl-progress-bar>

API

Component has a range of properties to define the experience in different use cases.

Properties

Name	Attribute	Type	Default	Description
`indeterminate`	`indeterminate`	`boolean`	`false`	Whether the progress bar has the indeterminate state.
`label`	`label`	`string \| undefined`		Label describing the value of the progress bar.
`value`	`value`	`number`	`0`	Progress value (from 0...100).
`variant`	`variant`	`'success' \| 'warning' \| 'error' \| undefined`		The variant of the progress bar.

Slots

Name	Description
`default`	A place for helper text like e.g. `20% of 100%`.

Accessibility considerations

Announcement of progress (for screen readers): Screen reader users receive updates about the progress as it changes. The value is announced when it changes, but not more often than once every 1,5 seconds. When it reaches 100% it immediately reads it out, inclusing the current state (for example 'success' or 'error').
Error States and feedback: In case of error states, such as when the progress bar indicates an error condition, keyboard users should receive appropriate feedback. Use for example an inline message, which uses the announcer to provide screen readers means to alert the user (using aria-live functionality) or make your own, custom, element using aria-live functionality. If the progressbar will never reach 100% because of the error let the screen reader user know what is happening and what they can do to remedy it by using a container with aria-live or use the announcer function.

WAI-ARIA

WAI-ARIA Roles, States, and Properties for a progress bar provide essential information to assistive technologies and screen readers.

Attribute	Value	Description	User suppliedSpecifies whether the attribute is always set in the component (no) or it needs to be provided by the developer (yes)
`role`	`'progressbar'`	This role indicates that an element represents a progress bar. It is used for both determinate (where progress is measurable, like a percentage) and indeterminate (where progress is ongoing without specific measure) progress bars.	no
`aria-valuemin`	string	Specifies the minimum value of the progress bar - 0 (0%).	no
`aria-valuemax`	string	Specifies the maximum value of the progress bar - 100 (100%).	no
`aria-valuenow`	string	Indicates the current value/progress of the progress bar (as percentage). This attribute is updated dynamically as the progress changes. For example, if the progress is at 50%, aria-valuenow would be set to 50.	no
`aria-live`	`polite`	Announces the state and value update/changes.	no
`aria-busy`	boolean	Set to `true` when the progress bar is in the `indeterminate` state on the aria-live element, otherwise it's set to `false`. You can also set `aria-busy="true"` when you want to connect the progress bar with other element/region on your application (please remember to connect the element/region with the progress bar component by e.g. by `aria-describedby`).	no/yes
`aria-labelledby`	string	Specifies a label or a reference to an element that serves as a label for the progress bar. This helps in associating the progress bar with its descriptive text or label for better understanding. By default, it contains `id` of the label (provided by `label` attribute). You can also connect the component with other label element using its `id` when there is no label attribute.	no/yes
`aria-describedby`	string	Identifies elements that provide additional descriptive information about the progress bar. This can include hints or additional explanations that assistive technologies can present to users. By default, it contains `id` of the slotted helper text. You can also add `aria-describedby="progress-bar-id"` on other element of your application to connect it with the progress bar component.	no/yes
`aria-label`	string	Can be added, when the progress bar has no label attribute.	yes

Interactive example