Progress indicators display the status of load times, processes, and user behaviors (such as savings goals or spending habits).
Progress indicators should be used wherever possible to inform the user of system status. Use the default animations when a loading experience is expected to be less than 10–15 seconds. When a loading experience is expected to take longer than 15 seconds, a custom indicator should be designed to make the experience as delightful and informative as possible. The progress indicator component is not considered to be a custom indicator.
Progress indicators appear in a wide variety of ways throughout the platform. In general, their uses can be split into two types of progress: Determinate and Indeterminate.
Determinate vs Indeterminate
A process can be defined as determinate only if the end value (such as the length of time, size of download, etc.) is a known and fixed amount. A process is inherently indeterminate when the end value is unknown or varied. While indeterminate progression experiences generally describe that of a loading process, determinate progress indicators may be used to describe the time of a loading process, workflow, or user behavior (such as savings goals or spending habits).
Please note: Not all loading experiences use progress indicator component. Use the table below to determine the best loading experience for a variety of use cases.
Determinate progress indicators may be used to display system status for loading, workflows, or user progress. When a determinate loading experience is expected to take longer than 10–15 seconds, include a time estimate. Determinate loaders come in three varieties: Bar, Circular, and Viewport.
- Heading — Subtitle 1 (Optional)
- Retry action — small no emphasis quick action button (Optional)
- Cancel action — small no emphasis quick action button (Optional)
- Helper/error text (Optional)
The stacked bar loader includes additional items to support previewing the loading process of a single item within a list. This loader may encounter an error state and swap the helper text to error messaging.
Please note: the quick action button extension should only show the cancel quick action button until an error occurs. For more information, see States below.
- Label — Caption (Optional)
- Percentage — Caption (Optional)
The inline determinate bar may commonly be used without any labels.
The circular determinate progress indicator fills clockwise starting at the top-center point of the circle.
The viewport determinate loader may be used to signify the loading process of a user interaction that does not occur within an affordance. This progress indicator moves linearly from left to right signifying the processing from 0–100%. Viewport loaders span the width of a context. The progress indicator is pinned to the bottom of the top bar (if a top bar is present). This progress indicator is not affected by shape theming.
Indeterminate progress indicators are primarily used to indicate system loading as the result of a user interaction. Indeterminate loaders are best used within affordances (such as a button, text field, or quick action button) to provide feedback for user interaction. Do not ever display more than one indeterminate “spinners” at a single time within a view.
Indeterminate progress indicators come in two varieties: Circular and Viewport.
The circular indeterminate progress indicator often appears within an avatar as part of another interactive organism (e.g. button, chip, cloaked checkmark, etc.). Avoid displaying two of these at a time. This loader should never be used to display the loading of a new page. Instead, it is better to use skeleton states to load content as it becomes available, allowing users to engage with the page content quicker. When the load process will likely take more than 7 seconds, consider using the confirmation activity loaders with an estimate or process description description.
The viewport indeterminate loader may be used to signify the loading process of a user interaction that does not occur within an affordance. This loader may be implemented using the Lottie files documented below. The animation features a cycling, non-linear movement of the indicator to signify indeterminate processing. Viewport loaders span the width of a context. The progress indicator is pinned to the bottom of the top bar (if a top bar is present). This progress indicator is not affected by shape theming.
While each loader is built with default colors, these may also be overridden by the context. For example, an indeterminate loader defaults to a ∆colorBrandedGuidanceAccessible color; whenever this loader appears in a high emphasis button, the indicator should consume the tokens defined by that component (∆colorBrandedAffordanceOn). For another example, if a determinate progress bar is used to display a user’s progress towards a goal, the defaults may be overridden such that a colorPlatformGray200 token is applied to the track and a colorBrandedSuccess400 token is applied to the indicator.
Size — Circular
Size — Bar
Size — Viewport
Spacing — Determinate Bar
While most progress indicators do not require consideration for states, determinate bar loaders will commonly be used in scenarios where errors may occur. For that reason, an error state has been defined, replacing the helper text with error messaging while overriding the track and indicator colors with the ∆colorBrandedErrorAccessible token.
Progress indicators are designed to reinforce theming through subtle variations in shape. For each variant there are a number of theming options, each with their own parameters.
With the exception of the viewport variants, all progress indicators should be placed adjacent to the content they describe. When an affordance triggers an indeterminate loader, the loader should be positioned as or replace the trailing icon. When any progress indicator is used as the only content on a screen, it should be placed in the center of the context.
Never use an indeterminate loader to show a page is loading. Instead, use skeleton states on the atoms to reduce cognitive load as items load in.
Both varieties of the indeterminate loader may be implemented using Lottie. Download the json files for each at Tools > Lottie files.
Indeterminate — Circular
Download the indeterminate circular Lottie files at Tools > Lottie files. Please reference the globstar mappings to create themed overrides.
Indeterminate — Viewport
Download the indeterminate viewport Lottie files at Tools > Lottie files. On all small and medium viewports, use the Small file linked below. For larger viewports, use the Large file linked below. Please reference the globstar mappings to create themed overrides.
Developer DocsVue Developer Docs
Component documentation coming soon!