A progress bar is a linear indicator for providing feedback about an ongoing, user-initiated process.

Design Guidelines

Usage

Clarity has two types of progress bars:

  • A determinate progress bar, which shows process completion to a specific maximum goal. Use this when the process has a known duration. This could be a file download or upload. Or, a series of configuration steps that happen during an initialization process.
  • An indeterminate progress bar, which animates continuously until the process is complete. Use this progress bar for a process when there is no estimate of the end time. It indicates that work is occurring without indicating a scope for completion or implying an estimate for how long it will take.

Placement

Progress bars are designed for use in the main content area, header, cards, and modals. The size of the progress bar adjusts to its container and indicates which process is being monitored through placement of the progress bar in the container.

Header
Header
Content area

Card title

Card text

Card top

Card title

Card text

Card footer

Card title

Card text

Card block

Messaging

50%
Determinate Progress Bar
  • Shows progress to a specific maximum goal
  • Has an optional label that shows percentage completion
  • Keep messaging minimal
  • Use specific messaging: Process starting, Process finished, etc
Processing step 3 of 4
Indeterminate
  • Uses specific messaging: E.g "Loading update 3 of 7"
  • Will animate continuously until complete
  • Has no estmated end time
  • Indicates work is occuring

Clarity places the label on the right of the progress bar because the bar fills from left to right.

Progress Bar Versus Spinner

Clarity also has a circular progress indicator, called a spinner, which serves the same use case as an indeterminate progress bar. Using a spinner or an indeterminate progress bar is a matter of available space and activation point. In many cases, spinners are best because they occupy less space.

Accessibility

When adding a progress bar, keep the following in mind when adding a label to make it accessible:

  • A label should always be included with a progress bar
  • Use aria-labelledby along with an id in order to tie the label and the progress bar together
  • Never use color as the only affordance that indicates the nature or meaning of the progress bar
  • Use an explicit text label that conveys the nature or meaning of the progress bar for sight impaired users
  • Labels should be added above or below the progress bar
  • An optional percentage label can be included after the progress bar as needed
  • While explicit text labels are preferred, an accessible icon is acceptable when vertical text labels are deemed inappropriate

Note: When the optional percentage label is used it must be associated with the progress bar it is describing. This can be accomplished by using the id of the percentage label with the aria-describedby attribute on the progress bar. The following form demonstrates an accessible progress implementation that meets both visual and screen reader consumption needs.

Label examples

An explicit label accurately describes the operation for which the progress/status is being updated by the progressbar

Generic Labels
  • Progress
  • Starting
  • Stopping
Explicit Labels
  • Adding VM
  • Uploading image
  • Downloading data

Deprecations

Several variations of progress bar have been found to be inaccessible and are now deprecated. They will be removed in Clarity v4.0. The following variations of progress-bar are not accessible to screen reader users or visually impaired users because they rely on recognition of the color to convey meaning or status.
  • Flash
  • flash-danger
  • danger
  • warning
  • success

Code & Examples

Progress bars consist of an HTML5 progress element inside the block-level element with the .progress classname. The block-level container is necessary due to cross-browser constraints with styling HTML5 progress elements. As browsers improve, the intent is for this container to go away.

Indeterminate (Looping) Progress Bars

When the amount of time a task will take is not known, use an indeterminate (or looping) progress bar. These progress bars feature a recurring animation that continues until the task is complete and the progress bar is no longer needed.

Color

The default color of the fill bar is Action Blue. You may change the color as required by visual design.

Using color to convey additional information e.g. Green to indicate Success is not recommended. Sight impaired users may not read the additional meaning without additional information such as a text label or icon. The recommendation if such status information is needed in the context of a progress bar, is to communicate this with a notification or text label.

Animation

Progress bars have options for animation.

  • Use fade animation when you want the progress bar to disappear with a fade.
  • Use flash animation to draw the user’s attention when the process has completed.

Variations

The animation, color, and type of a progress bar can be changed by adding or removing CSS classes from the following list of class names.

  • labeled: A progress container with the labeled classname will show the percent complete as a numerical percentage to the far right of the progress bar. Note that this requires a <span> element be placed within the container after the <progress>. You will also need to update the contents of the span programmatically.
  • progress-fade: A progress container with the progress-fade classname will fade out after it reaches 100%.
  • flash: A progress container with the flash classname will have the bar color change to green after it reaches 100%. This can be combined with the progress-fade classname to have the bar change color to green and then fade out. This has been deprecated in Clarity v3.0 and will be removed in v4.0
  • flash-danger: A progress container with the flash-danger classname will have the bar color change to red after it reaches 100%. This classname can also be combined with the progress-fade classname. This has been deprecated in Clarity v2.0 and will be removed in v4.0
  • loop: A progress container with the loop classname will show a progress bar that loops across infinitely. This is the style for our indeterminate progress bar.
  • danger: A progress container with the danger classname will show up as red. This has been deprecated in Clarity v2.0 and will be removed in v4.0
  • warning: A progress container with the warning classname will also show up as red. This has been deprecated in Clarity v2.0 and will be removed in v4.0
  • success: A progress container with the success classname will show up as green. This has been deprecated in Clarity v2.0 and will be removed in v4.0

Progress Bar in Cards

Static Progress Bar in Cards

Progress Bar in Sidebar Navigation

Static Progress Bars

Some applications use progress bars inside other widgets that re-render repeatedly in the DOM. While this is not a pattern that Clarity promotes, we have implemented a “static” progress bar to assist in these uses.

A normal progress bar will animate from its starting point to the defined ending point. When widgets that contain progress bars are re-rendered in the DOM, this results in Clarity’s progress bars continually growing from zero to the defined value.

A static progress bar just shows the defined value. It does not animate and lend itself to these sorts of DOM refreshes.

Because there was no way to turn off the animation in IE/Edge’s implementation of the HTML5 progress element, there is a related, though separate, component for static progress bars.

  • Instead of a .progress container div, the static progress bar has a .progress-static container div.
  • Instead of a progress element inside the container, there is a div</codeAtom> with the class of .progress-meter applied to it.
  • A div cannot have a value attribute, so the .progress-meter element has data-value attribute. The completion value must be dynamically inserted in the data-value attribute.
  • The data-value attribute must contain an integer between 0 and 100.

Progress Bar Blocks and Groups

Progress bar blocks allow for label and span elements to be placed alongside the .progress and .progress-static element. The progress bar block is a wrapper element with the .progress-block classname applied to it.

Progress bar groups allow for vertical stacking of elements above and below the progress bar. To create a progress bar group, wrap the .progress and .progress-static element with a .progress-group element.

Progress bar blocks are also available for use inside of Clarity cards.