Anatomy
- Background: The background fill of the progress bar
- Foreground: The part of the bar that animates
Usage Guidelines
When to use this component
- Use a progress bar when a process is running in the background and the user needs to wait for its completion.
When not to use this component
Don't use a progress bar for tasks that are instant or take only a few seconds. The bar itself can be a distraction and might make a fast process feel slower.
- For Instant Actions: Avoid using a progress bar for actions that are almost immediate, such as a quick data save or a simple button click that triggers a near-instant response.
- As a Decorative Element: A progress bar should serve a clear purpose. Don't use it as a purely visual element, as it can confuse the user into thinking something is happening when it isn't.
- When the Process is Uninterruptible: If the user can't stop or cancel the process, a progress bar can create a sense of helplessness. It's often better to show a simple spinner or a static message instead.
Best Practices
Use it when the process can be described with quantitative information, such as a percentage. For instance, uploading a file.
Don't use it to represent stepped progress that is determined by user actions. Use a step indicator instead.
You can provide additional content when necessary and always use an aria-label when using the progress bar. Check extended practices on accessibility below.
Don’t use it in small spaces or when you need to display an indeterminate state. Use the spinner instead.
Don't use it for data visualization or progress that requires user actions. For now, use a custom component instead.
General Component Behaviors
Our progress bar is determinate, meaning the total time or amount of work is known. It's main behaviors are:
- Progressive Fill: The bar fills up from one end to the other as the process advances. The length of the filled section is directly proportional to the percentage of completion.
- Predictable End: The bar reaches 100% and disappears or changes to a success state when the task is finished.
- Pausing/Resuming: The bar may stop filling if the process is paused and resume from where it left off.
States
Known Gaps
- Updated accessibility guidance