Progress Indicators

Approved — Ready for dev

Progress indicators display the status of load times, processes, and user behaviors (such as savings goals or spending habits).

Progress Indicators

Anatomy

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.

Load Average length Loader
Indeterminate (interaction) < 10–15 seconds Indeterminate component
Indeterminate (interaction) > 10–15 seconds Custom (indeterminate)
Indeterminate (page/content) < 10–15 seconds Skeleton states
Indeterminate (page/content) > 10–15 seconds Custom (indeterminate)
Determinate < 10–15 seconds Determinate component
Determinate > 10–15 seconds Custom or determinate component with description

Determinate

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.

Bar

Stacked
  1. Indicator(s)
  2. Heading — Subtitle 1 (Optional)
  3. Retry action — small no emphasis quick action button (Optional)
  4. Cancel action — small no emphasis quick action button (Optional)
  5. Track
  6. 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.

Inline
  1. Label — Caption (Optional)
  2. Indicator(s)
  3. Track
  4. Percentage — Caption (Optional)

The inline determinate bar may commonly be used without any labels.

Circular

  1. Indicator
  2. Track

The circular determinate progress indicator fills clockwise starting at the top-center point of the circle.

Viewport

  1. Indicator
  2. Track

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

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.

  1. Indicator

Indeterminate progress indicators come in two varieties: Circular and Viewport

Circular

  1. Indicator

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.

Viewport

  1. Indicator
  2. Track

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.

Specs

Color

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.

Element Property Value
Track Color ∆colorBrandedGuidance200
Indicator Color ∆colorBrandedGuidanceAccessible
Determinate bar track (Error) Color ∆colorBrandedErrorAccessible
Determinate bar indicator (Error) Color ∆colorBrandedErrorAccessible

Size — Circular

Element Property Value
Track and indicator (xsmall) Stroke width 2
Track and indicator (small) Stroke width 2
Track and indicator (medium) Stroke width 3
Track and indicator (large) Stroke width 3
Track and indicator (xlarge) Stroke width 4
Track and indicator (xsmall) Size 18
Track and indicator (small) Size 24
Track and indicator (medium) Size 32
Track and indicator (large) Size 40
Track and indicator (xlarge) Size 56

Size — Bar

Element Property Value
Track Width Defined by design
Track and indicator (small) Height 4
Track and indicator (medium) Height 8
Track and indicator (large) Height 16

Size — Viewport

Element Property Value
Track and indicator Width 100%
Track and indicator Height 4

Spacing — Determinate Bar

States

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.

Theming

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.

Circular

Element Shape Property Value
Indicator Sharp Cap style None
Indicator Soft Cap style Rounded
Indicator Squircle Cap style Rounded
Indicator Rounded Cap style Rounded

Bar

Element Shape Property Value
Track and indicator (Small) Sharp Surface radius 0
Track and indicator (Small) Soft Surface radius 1
Track and indicator (Small) Squircle Surface radius 2
Track and indicator (Small) Rounded Surface radius 2
Track and indicator (Medium) Sharp Surface radius 0
Track and indicator (Medium) Soft Surface radius 2
Track and indicator (Medium) Squircle Surface radius 3
Track and indicator (Mediuml) Rounded Surface radius 4
Track and indicator (Large) Sharp Surface radius 0
Track and indicator (Large) Soft Surface radius 4
Track and indicator (Large) Squircle Surface radius 6
Track and indicator (Large) Rounded Surface radius 8

Placement

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.

Behavior

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.

Element Globstar Default value
Indicator .indicatorColorDynamicStroke ∆colorBrandedGuidanceAccessible

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.

Element Globstar Default value
Indicator .indicatorColorDynamicStroke ∆colorBrandedGuidanceAccessible
Indicator .trackColorDynamicStroke ∆colorBrandedGuidance200

Developer Docs

Vue Developer Docs

Component documentation coming soon!