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.
<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.
Quantitative information
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. |
<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 should receive updates about the progress as it changes. This can be achieved by updating the aria-valuenow attribute and/or announcing changes in percentage or value through ARIA live regions (both are provided by the component).
- 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. This can include announcing the error through ARIA live regions or focusing on an error indicator. By default, the component uses
aria-live="polite"(to announce the status and progress change). However, in cases where there is an error, it can be useful to usearia-live="assertive". In such situations, the aria-live attribute needs to be added to an element other than the progress bar itself. For example, it could be added to a field that is connected to the progress bar and may cause an error.
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 supplied |
|---|---|---|---|
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 |