Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,14 @@ id: Progress stepper
section: components
---

import '../components.css';

A **progress stepper** displays progress through a sequence of linear steps and highlights what step the user is currently on.

## Elements
<img src="./img/progress-stepper-elements.png" alt="Image showing the different elements that can be contained in a progress stepper." width="1514" />
<div class="ws-docs-content-img">
![Elements of a progress stepper.](./img/stepper-elements.svg)
</div>

1. **Progress title:** Describes the task or process underway.
2. **Progress description (optional):** Provides additional information on the task or process
Expand All @@ -22,17 +26,25 @@ Use a progress stepper to convey to a user how many steps are required to comple
### When to use
* A user is completing a multi-step process in a card

<img src="./img/progress-stepper-card-view.png" alt="Image showing example of progress stepper in a card view." width="1600" />
<div class="ws-docs-content-img">
![Example of a progress stepper in a card.](./img/multi-stepper-card.svg)
</div>

* A user is showing progression through a workflow in a table or card

<img src="./img/progress-stepper-table-view.png" alt="Image showing example of progress stepper in a table view." width="1319" />
<div class="ws-docs-content-img">
![Example of a progress stepper in a table.](./img/stepper-table.svg)
</div>

<img src="./img/progress-stepper-canvas-view.png" alt="Image showing example of progress stepper in a card view." width="1600" />
<div class="ws-docs-content-img">
![Example of a progress stepper in a card.](./img/stepper-card.svg)
</div>

* A user is checking the status of the installation process in a popover

<img src="./img/progress-stepper-table-view-popover.png" alt="Image showing example of progress stepper in a table view with a popover." width="1600" />
<div class="ws-docs-content-img">
![Example of a progress stepper in a popover.](./img/stepper-popover.svg)
</div>

### When to use progress stepper vs. wizard

Expand All @@ -50,32 +62,44 @@ There are a few variations of the progress stepper that can be used for differen
### Basic progress stepper
The basic progress stepper can be used when just the title of the step is enough to inform the user.

<img src="./img/progress-stepper-basic.png" alt="Image showing example of a basic progress stepper." width="595" />
<div class="ws-docs-content-img">
![Example of a basic progress stepper.](./img/stepper-basic.svg)
</div>

### Basic with descriptions
If more description is needed, a basic progress stepper with descriptions can be used which allows for more context for each step.

<img src="./img/progress-stepper-with-description.png" alt="Image showing examples of a basic progress stepper with descriptions." width="1317" />
<div class="ws-docs-content-img">
![Example of a progress stepper with descriptions.](./img/stepper-with-descriptions.svg)
</div>

### Vertical progress stepper
The vertical alignment can be used in pages with a split view where one side houses the progress stepper and the other side houses each step’s content. These can also be used to display progress in a popover.

<img src="./img/progress-stepper-vertical.png" alt="Image showing examples of a vertical progress stepper." width="676" />
<div class="ws-docs-content-img">
![Example of a vertical progress stepper.](./img/stepper-vertical.svg)
</div>

### Compact progress stepper
In areas with less real estate such as table rows, the compact progress stepper can be used. The component will not display as much information such as each step’s title and/or description and will be smaller in size. The compact progress stepper also accounts for the alignment variations.

<img src="./img/progress-stepper-compact.png" alt="Image showing examples of a compact progress stepper." width="1597" />
<div class="ws-docs-content-img">
![Example of a compact progress stepper.](./img/stepper-compact.svg)
</div>

### Progress stepper with icons
Custom icons can also be used for each step of the progress stepper based on the use case and the product’s need.

<img src="./img/progress-stepper-custom-icons.png" alt="Image showing example of a progress stepper with custom icons." width="575" />
<div class="ws-docs-content-img">
![Example of a progress stepper with custom icons.](./img/stepper-custom-icons.svg)
</div>

### Progress stepper with help popover
If additional help information or help text is needed and there is not enough real estate for a description, a popover on each step’s title can be used.

<img src="./img/progress-stepper-help-popover.png" alt="Image showing example of a progress stepper with help popver." width="586" />
<div class="ws-docs-content-img">
![Example of a progress stepper with a help popover.](./img/stepper-help-popover.svg)
</div>

## Content considerations
Progress steppers should be self-explanatory and therefore include minimal written content: A title and an optional description.
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,12 @@ id: Progress
section: components
---

import '../components.css';

## Elements
<img src="./img/progress-bar-callouts.png" alt="A progress bar with arrows pointing to each of its four elements: Its title, track, progress value, and indicator." width="608" />
<div class="ws-docs-content-img">
![Elements of a progress bar.](./img/progress-elements.svg)
</div>

1. **Title:** Describes the task or process underway.
2. **Track:** Illustrates the path from task start (empty) to task completion (full).
Expand All @@ -25,7 +29,6 @@ Depending on your use case, you might choose between 2 types of loading indicato
Default to progress bars for processes that take longer than 4 seconds or require more specific information about process completion. If a process takes less than four seconds, use a [spinner](/components/spinner) instead.

## Variations
<img src="./img/progress_bar_blue_animated.gif" alt="An animated progress bar demonstrates how a progress track fills and progress value increases as a process moves toward completion." width="500" height="300" />

### Determinate progress bar

Expand All @@ -46,19 +49,25 @@ Follow these general style guidelines when designing your progress bars. For inf

A blue progress bar represents a process that is currently underway.

<img src="./img/progress-bar-in-progress.png" alt="An example of a progress bar in an 'in progress' state, with a blue track and a title that indicates its status: 'Validating account credentials.'" width="560" />
<div class="ws-docs-content-img">
![Example of a progress bar in the "in progress" state.](./img/in-progress.svg)
</div>

### Error state or failure

A red progress bar represents a process that has failed. Accompany a failed progress bar with a [red danger icon](/design-foundations/icons/#all-icons) to demonstrate that an error occurred in the process.

<img src="./img/progress-bar-error-state.png" alt="An example of a progress bar in an error or failed state, with a red track, optional danger icon, and a title that indicates its status: 'Could not validate account credentials.'" width="560" />
<div class="ws-docs-content-img">
![Example of a progress bar in the error or failed state.](./img/error.svg)
</div>

### Complete or success

A green progress bar represents the successful completion of a process. Accompany a complete progress bar with a [green check-circle icon](/design-foundations/icons/#all-icons) to demonstrate that the process has finished with no errors.

<img src="./img/progress-bar-complete.png" alt="An example of a progress bar in a complete or successful state, with a green track, optional check-circle icon, and a title that indicates its status: 'Validated account credentials.'" width="560" />
<div class="ws-docs-content-img">
![Example of a progress bar in the complete or successful state.](./img/success.svg)
</div>

### In a table

Expand All @@ -68,46 +77,59 @@ Place a progress bar into a table just as you would other table content. If a pr

If your table includes multiple progress bars, designate a “Status” or “Progress” column for each one.


<img src="./img/progress-bar-in-table.png" alt="A visual example of how to successfully place progress bars in a table." width="543" />
<div class="ws-docs-content-img">
![Example of progress bars in a table.](./img/progress-table.svg)
</div>

### In a dashboard view

Use a progress bar in a dashboard view to track the progress trends within each card component on a page.

<img src="./img/progress-bar-in-dashboard.png" alt="A visual example of how to successfully place progress bars in dashboard views." width="543" />
<div class="ws-docs-content-img">
![Example of a progress bar in a card on a dashboard.](./img/card-dashboard.svg)
</div>

### During a file download

Use a [toast notification](/components/alert/design-guidelines/#using-toast-alerts) and a progress bar to demonstrate progress during a file download.

<img src="./img/progress-bar-during-file-download.png" alt="A visual example of how to successfully place progress bars in toast alerts to communicate progress during a file download." width="543" />
<div class="ws-docs-content-img">
![Example of a progress bar in a toast alert to communicate progress during a file download.](./img/progress-file-download.svg)
</div>

### In a wizard

**Never** use a progress bar in a wizard to indicate progress through wizard steps, since a wizard’s steps sidebar already communicates this information.

Only use a progress bar in a wizard if its final validation process will take more than a few seconds. As users wait for their changes to be processed, display a progress screen that includes a progress title, progress bar, and an optional 1-2 sentence description to provide more details about the validation step or give users a better idea of how long this process might take.

<img src="./img/progress-bar-in-wizard.png" alt="A visual example of how to successfully place a progress bar in a wizard to express a final validation process." width="543" />
<div class="ws-docs-content-img">
![Example of a progress bar in a wizard.](./img/progress-wizard.svg)
</div>

To learn more about using progress bars in wizard validation progress screens, see our [wizard guidelines](/components/wizard/design-guidelines).

## Spacing

Right-align progress value text when it’s placed above the progress track, in line with the title.

<img src="./img/progress-bar-right-aligned-progress-value.png" alt="A visual example of a progress bar with right-aligned progress value text above the progress track." width="560" />
<div class="ws-docs-content-img">
![Example of a progress bar with right-aligned value text above the progress track.](./img/progress-number-above.svg)
</div>

Left-align progress value text when it’s placed to the right of the track.

<img src="./img/progress-bar-left-aligned-progress-value.png" alt="A visual example of a progress bar with left-aligned progress value text in line with the progress track." width="616" />
<div class="ws-docs-content-img">
![Example of a progress bar with left-aligned value text in line with the progress track.](./img/progress-number-outside.svg)
</div>

Always set an “outside fixed width measure” for determinate progress bars. This fixed spacing should solve alignment use cases in which stacked progress bar values vary in length.

## Placement

<img src="./img/progress-bar-do-dont.png" alt="A visual example of how to successfully place a progress bar in your designs, side by side with an example of unsuccessful placement. Never isolate a progress bar above, below, or outside of its corresponding content view — always align it with its relevant content." width="1135"/>
<div class="ws-docs-content-img">
![Examples of dos and don'ts for placing a progress bar in your designs.](./img/progress-placement.svg)
</div>

Always place progress bars in alignment with their relevant context, such as the feature, function, or task they reflect. Keep progress bars within the user’s line of sight: Never isolate a progress bar at the top or bottom of a page, or outside of its relevant content view.

Expand Down