Progress bar
A progress bar shows how much is done and how much is left to finish.
Published: Last updated:
Overview
A progress bar visually communicates that a task or process is underway and shows how much of it has been completed. It helps users understand that their request is being processed and gives a sense of progress or remaining time.
When to use
- For operations or processes that take a noticeable or uncertain amount of time to complete.
- When the progress can be measured or expressed quantitatively, such as with a percentage.
- To visually represent the progression of system tasks like downloading, uploading, loading data, submitting a form, or saving updates.
- To indicate that data is being requested, transferred, or processed.
When not to use
- When loading time is short and used to reveal additional content, use skeleton states instead.
- When user interaction is needed to move forward, use a progress stepper instead.
- When progress depends on user actions (e.g., sections completed, storage space) rather than system processes.
- When the process completes in less than five seconds, use a loading spinner instead.
Variants
A progress bar can be either determinate or indeterminate. The determinate variant displays a track that fills from left to right to represent measurable progress toward completion. The indeterminate variant displays a continuously moving bar to indicate an ongoing process when the exact duration or progress is unknown.
|
Variant
|
Purpose
|
|---|---|
| Determinate | Use determinate progress bars when progress can be measured. They show a clear, quantitative indication of completion. |
| Indeterminate | Use indeterminate progress bars when progress can’t be measured. They show that a process is ongoing without indicating how long it will take. |
Determinate progress bar
Determinate progress bars are used when loading progress can be tracked and displayed as a bar filling the track from 0% to 100%, without decreasing or resetting.
Use a determinate progress bar when progress can be measured against a specific goal. For example, downloading a file of a known size.
Indeterminate progress bar
Indeterminate progress bars are used when the loading progress is unknown or the wait time cannot be calculated.
Once triggered, the bar moves continuously from left to right while data is being processed. In this state, no percentage value is displayed. If enough information becomes available to calculate progress, the bar can switch to a determinate variant to visually indicate completion of the task.
Downloading
For download actions, it is usually possible to track progress and update a determinate progress bar in real time. When supported by the data source, an estimated time remaining can be calculated based on the amount downloaded over a given period.
Uploading
Upload actions may not always provide real-time progress updates, depending on the data source and API configuration. Whenever possible, use a determinate progress bar to inform users of the ongoing process.
Data processing
Data processing involves manipulating data to produce meaningful results, such as file generation, currency conversions, or data reformatting. Depending on the operation, estimated time or processing cycles can be used to populate a determinate progress bar.
- Label text: Describes the process the progress bar represents. The label may be visually hidden but must always be present for accessibility.
- Helper text: Provides additional context about the process. In determinate progress bars, this often shows a percentage, fraction, or numeric value to indicate progression. Indeterminate progress bars do not display numeric values. When an error occurs, the helper text must describe the problem.
- Note text: Provides extra context for the progress bar when needed, such as a readable percentage of completion or a target goal, like an expected finish date.
- Track: The fixed background area that represents the total scope of the process and serves as a reference for progress.
- Indicator bar: The moving element that visually represents the completion level of the process.
- Status icon: Communicates the current status of the progress bar, such as success or error.
Height
Progress bars are available in two sizes: Large (8px) and small (4px). The large progress bar is typically used when there is ample space in the layout, such as full-width sections or standalone loading states.
The small progress bar is designed for compact areas where space is limited, such as inside cards, data tables, or side panels.
Content
Both determinate and indeterminate progress bars include a label and optional helper text.
However, indeterminate progress bars can’t display specific, quantitative details about progression in the helper text.
Labels
- Labels describe what process or information the progress bar represents.
- Keep labels short and direct, ideally a few words or a single line of text.
- Label text should remain consistent throughout the process and does not need to change once the progress completes, as completion or errors are communicated through the bar colour, status icon, and helper text.
Note text
- Note text offers supplementary context to the progress bar, supporting the label and helper text.
- It can include meaningful information such as a readable percentage (“83%”) or a target goal (“Ending October 26”).
- Keep note text brief and informative, focusing on key progress details that help users understand the status at a glance.
Helper text
- Helper text provides additional context about the process.
- It may include a general phrase such as “Fetching assets…” or a quantitative indicator like “42/256 items”.
- For determinate progress bars that display a percentage, the value should increase smoothly as the bar advances.
Statuses
There are three statuses for the progress bar: active, success, and error.
These statuses apply to both determinate and indeterminate progress bars.
After a process completes, either successfully or unsuccessfully, the progress bar may remain visible to provide confirmation or validation, or it may be automatically dismissed, depending on what best suits the use case.
Active
The active status is shown with an animated blue progress bar, indicating that the process is ongoing.
Success
The success status, displayed as a full-width green bar with a checkmark icon, confirms that the process has finished successfully.
Error
The error status shows that the process did not complete successfully. When an error occurs, the bar fills to full width, turns red, and remains visible with an error icon. An inline notification or form error message should also appear to provide further context.
Part of a page
When the progress bar is active on part of a page, users can continue interacting with other elements. Once the process is complete, the progress bar may either remain visible for confirmation or automatically disappear, depending on the context and purpose of the action.
Inside a container
When the progress bar processes information that affects multiple elements within a container (such as a card), the affected area should become inactive until processing is complete. Depending on the use case, this may apply to the entire container or only the specific section being updated. Users should still be able to interact with other parts of the container or page that are not impacted by the progress.
Transitions
An indeterminate progress bar can transition into a determinate one once enough data is available to measure progress. The bar should then continue filling from left to right until completion, providing users with a clear visual cue that the process is nearing completion.
Expressive colours
Progress bars can use the expressive colour palette to override their default styling. Expressive colours provide flexibility beyond the default styles.