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.

Variations

• Large Determinate Example (shown above)
• Large Indeterminate Example
• Small Determinate Example
• Small Indeterminate Example
• Extra Small Indeterminate Examples

Usage

There are two types of indicators: determinate and indeterminate. Both determinate and indeterminate progress indicators may include brief messaging about what action is being taken. See Voice and Tone for guidance on messaging.

Variations

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 buttons, form fields and table cells

Large Indeterminate

Small Determinate

Small Indeterminate

Extra Small Indeterminate

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 to function. You must instantiate the indicator using either the jQuery plugin (var progress = $('#progress').sparkProgressIndicator();) or the native JavaScript implementation (var progress = new Spark.ProgressIndicator(document.querySelector('#progress'));).

It is important to store a reference to the created instance because the value is updated using the set method and passing a floating point number from 0-1. Numbers greater than 1 will be treated as 1.

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>

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

// jQuery
$('.spark-progress').sparkProgressIndicator();
$('.spark-progress').sparkProgressIndicator('set', 0.5); // Set to 50% complete

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>

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

// jQuery
$('.spark-progress').sparkProgressIndicator();

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>

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

// jQuery
$('.spark-progress').sparkProgressIndicator();
$('.spark-progress').sparkProgressIndicator('set', 0.5); // Set to 50% complete

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>

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

// jQuery
$('.spark-progress').sparkProgressIndicator();

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

Extra Small Indeterminate

<button class="spark-btn spark-btn--sm spark-progress">
  <progress></progress>
  <span class="spark-progress__meter"></span>
  Loading
</button>

<hr />

<button class="spark-btn spark-btn--sm spark-btn--secondary spark-progress">
  <progress></progress>
  <span class="spark-progress__meter"></span>
  Loading
</button>

<hr />

<button class="spark-btn spark-btn--sm spark-btn--alt spark-progress">
  <progress></progress>
  <span class="spark-progress__meter"></span>
  Loading
</button>

An extra small loader is created by adding .spark-progress, to a <button> element with the .spark-btn and .spark-btn--sm classes. Additional button classes may be added to customize the color. Do not use determinate loaders at this size.