Progress Indicators

Large Determinate Example

When to Use

• Use a determinate indicator to communicate the percentage of completion when this value is known and when it is helpful to communicate this to the user.
• Use an indeterminate indicator to communicate that an action is being performed by the application, but the percentage of completion is unknown. An indeterminate indicator can also be used when the action happens so quickly that is seems unnecessary to communicate the percentage of completion.

Both determinate and indeterminate progress indicators may include brief messaging about what action is being taken. See Voice and Tone for guidance on messaging.

Examples

Usage

There are two types of indicators:

• Determinate - A progress indicator that has exact and/or discernible limits (Example: 100% complete).
• Indeterminate - An indicator where the value or limit isn’t exactly established or defined (Example: Fetching stuff…).

Both determinate and indeterminate progress indicators may include brief messaging about what action is being taken. See Voice and Tone for guidance on messaging.

There are three sizes of indicators:

• Large - Use in full page context, such as splash screens.
• Small - Use in modals, panels and inline content.
• Extra Small - Use in form fields and table cells.

Progress Indicators may also display inside a button. See the Progress Button to view an example.

Examples

Large Indeterminate

Small Indeterminate

Extra Small Indeterminate

Small Determinate

Extra Small Determinate

Developer Notes

A loader is created by adding a class of spark-progress to an element. This element should also have the appropriate role="progressbar" ARIA attribute.

Whether or not a progress indicator is determinate or indeterminate is based on the presence of a value attribute on the <progress> element. A determinate loader has a value attribute (even without a value). Conversely, an indeterminate loader is defined as having no value.

Order matters

The first element contained inside a spark-progress container should be a <progress></progress> element. This is essential to defining a determinate or indeterminate state.

Any text which accompanies the loader should be placed inside an element with a class of spark-progress__text. For determinate loaders, an element with a class of spark-progress__value and role="status" should be placed inside the text container. This element will be updated with the current percentage of the loader.

You may also insert a <ul> with a class of spark-progress__states which contains different text values to be displayed when the <progress> element has different values. The <li> children of this list of states must use the attribute data-value along with an integer value from 0-100. These list items will be shown and hidden automatically as the progress indicator is incremented. For example, say you have three list items with data-value values of 0, 35 and 100. The first <li> will be shown when the progress value is from 0-34, the second from 35-99 and the last at 100.

Following the text, values, and states is the actual graphical representation of the loader. This is created by adding an element with the class spark-progress__meter. Although the initial markup is the same for a determinate or indeterminate loader, determinate loaders replace this meter element with a special SVG implementation of the loader.

This functionality relies on JavaScript. The following options may be passed when using new Spark.ProgressIndicator(el, {});:

For all available methods and full API, refer to the component code on Bitbucket.

Large Indeterminate

<div class="spark-progress spark-progress--integrated spark-progress--lg" role="progressbar">
  <progress></progress>
  <span class="spark-progress__text" role="status">Fetching stuff</span>
  <span class="spark-progress__meter"></span>
</div>

<style type="text/css">
  
</style>

// Vanilla JS
var el = document.querySelector('.spark-progress');
var progressInstance = new Spark.ProgressIndicator(el);

A large loader is created by adding .spark-progress, .spark-progress--integrated and .spark-progress--lg to an element.

Small Indeterminate

<div class="spark-progress spark-progress--horizontal spark-progress--sm" role="progressbar">
  <progress></progress>
  <span class="spark-progress__text" role="status">Fetching stuff</span>
  <span class="spark-progress__meter"></span>
</div>

<style type="text/css">
  
</style>

// Vanilla JS
var el = document.querySelector('.spark-progress');
var progressInstance = new Spark.ProgressIndicator(el);

A small loader is created by adding .spark-progress, .spark-progress--horizontal and .spark-progress--sm to an element.

Extra Small Indeterminate

<div class="spark-progress spark-progress--horizontal spark-progress--xs" role="progressbar">
  <progress></progress>
  <span class="spark-progress__text" role="status">Fetching stuff</span>
  <span class="spark-progress__meter"></span>
</div>

<style type="text/css">
  
</style>

// Vanilla JS
var el = document.querySelector('.spark-progress');
var progressInstance = new Spark.ProgressIndicator(el);

An extra small loader is created by adding .spark-progress, .spark-progress--horizontal and .spark-progress--xs to an element.

Large Determinate

<div class="spark-progress spark-progress--integrated spark-progress--lg" role="progressbar">
  <progress value="0"></progress>
  <span class="spark-progress__text">
    <span class="spark-progress__value" role="status">0%</span>
    <ul class="spark-progress__states" role="note">
      <li data-value="0" class="active">Applying Policy Rules</li>
      <li data-value="20">Sorting Options</li>
      <li data-value="40">Generating Jobs</li>
      <li data-value="60">Perturbing Matrices</li>
      <li data-value="80">Reticulating Splines</li>
      <li data-value="100">All done!</li>
    </ul>
  </span>
  <span class="spark-progress__meter"></span>
</div>

<style type="text/css">
  
</style>

// Vanilla JS
var el = document.querySelector('.spark-progress');
var progressInstance = new Spark.ProgressIndicator(el);
progressInstance.set(0.5); // Set to 50% complete

A large loader is created by adding .spark-progress, .spark-progress--integrated and .spark-progress--lg to an element.

Small Determinate

<div class="spark-progress spark-progress--horizontal spark-progress--sm" role="progressbar">
  <progress value="0"></progress>
  <span class="spark-progress__text">
    <span class="spark-progress__value"><span role="status">0%</span> complete</span>
    <ul class="spark-progress__states" role="note">
      <li data-value="0" class="active">Applying Policy Rules</li>
      <li data-value="20">Sorting Options</li>
      <li data-value="40">Generating Jobs</li>
      <li data-value="60">Perturbing Matrices</li>
      <li data-value="80">Reticulating Splines</li>
      <li data-value="100">All done!</li>
    </ul>
  </span>
  <span class="spark-progress__meter"></span>
</div>

<style type="text/css">
  
</style>

// Vanilla JS
var el = document.querySelector('.spark-progress');
var progressInstance = new Spark.ProgressIndicator(el);
progressInstance.set(0.5); // Set to 50% complete

A small loader is created by adding .spark-progress, .spark-progress--horizontal and .spark-progress--sm to an element.

Extra Small Determinate

<div class="spark-progress spark-progress--horizontal spark-progress--xs" role="progressbar">
  <progress value="0"></progress>
  <span class="spark-progress__text">
    <span class="spark-progress__value"><span role="status">0%</span> complete</span>
    <ul class="spark-progress__states spark-assistive-text" role="note">
      <li data-value="0" class="active">Applying Policy Rules</li>
      <li data-value="20">Sorting Options</li>
      <li data-value="40">Generating Jobs</li>
      <li data-value="60">Perturbing Matrices</li>
      <li data-value="80">Reticulating Splines</li>
      <li data-value="100">All done!</li>
    </ul>
  </span>
  <span class="spark-progress__meter"></span>
</div>

<style type="text/css">
  
</style>

// Vanilla JS
var progressInstance = new Spark.ProgressIndicator(el);
progressInstance.set(0.5); // Set to 50% complete

An extra small loader is created by adding .spark-progress, .spark-progress--horizontal and .spark-progress--xs to an element.