Progress Bar

Display the current progress of a task.

How to

The Progress Bar component can be used to display the progress of an operation.

To set the value of the progress, in the HTML file, make sure to:

• Set the text of the .progress-bar__value element equal to the percentage value:

<span class="progress-bar__value margin-bottom-xs text-sm color-contrast-medium" aria-hidden="true">30%</span>​

• Set the text of the .js-progress-bar__aria-value element equal to the percentage value:

<p class="sr-only" aria-live="polite" aria-atomic="true">Progress value is <span class="js-progress-bar__aria-value">30%</span></p>​

• Set, for the .progress-bar__fill element, an inline width equal to the percentage value:

<div class="progress-bar__fill" style="width: 30%;"></div>​

Animate Progress Bar

To animate the progress bar, add the [data-animation="on"] attribute to the .progress-bar element: when the progress bar enters the viewport, its fill value will be animated from 0 to the final value.

You can change the duration of the animation using the data-duration attribute (in ms). If this attribute is not provided, the default duration will be used (1000ms).

<div class="progress-bar js-progress-bar flex flex-column items-center" data-animation="on" data-duration="2000">
  <!-- ... -->
</div>

Dynamically Update Progress

There may be cases where you need to update the value of the progress bar dynamically (for example, while uploading a file or loading a video). To do that, you can use the updateProgress custom event.

Here's an example of how to update the value of a progress bar element from its initial value to 70%:

// make sure to select the proper progress bar element - in this example we take the first available one
var progressBar = document.getElementsByClassName('js-progress-bar')[0]; 
// define the custom event and set the final value of the progress (70) 
var event = new CustomEvent('updateProgress', {detail: {value: 70}});
// dispatch the event
progressBar.dispatchEvent(event);

You can also pass a custom duration (in ms) for the animation:

var event = new CustomEvent('updateProgress', {detail: {value: 70, duration: 3000}});

Update the Color of Progress Bar

You can change the color of the progress bar fill element based on its value.

To do that, add the .progress-bar--color-update class to the .progress-bar element. Inside this class, a CSS variable is defined for each color threshold.

By default, three thresholds are defined:

• --progress-bar-color-1: equal to 30. The fill color for this threshold is defined inside the .progress-bar--fill-color-1 class;
• --progress-bar-color-2: equal to 65. The fill color for this threshold is defined inside the .progress-bar--fill-color-2 class;
• --progress-bar-color-3: equal to 100. The fill color for this threshold is defined inside the .progress-bar--fill-color-3 class;

You can increase the number of those thresholds: make sure to define a .progress-bar--fill-color-{n} class for each --progress-bar-color-{n} variable.

Also, make sure the CSS variable values increment with the index (e.g., --progress-bar-color-{n+1} >  --progress-bar-color-{n}).

Accessibility

To make the Progress Bar component fully accessible, we have included a <p> element (with a class of sr-only so that it is visually hidden) that is announced to Screen Readers:

<p class="sr-only" aria-live="polite" aria-atomic="true">Progress value is <span class="js-progress-bar__aria-value">50%</span></p>

You can update the content of that paragraph to provide a more detailed description. Make sure you do not remove the .js-progress-bar__aria-value element and that its content is equal to the progress value. 

If the progress bar is dynamically updated, the content of that element will be updated as well so that the new value is announced to SR.

Categories

• Data Display > Progress
• Plugins > Misc

Bug report & feedback

Component Github page ↗