Circular Progress Bar

Display the current progress of a task using a circular SVG shape.

How to

The Circular Progress Bar component allows you to show the progress of a specific operation, using, as progress bar, a circular SVG shape.

The SVG progress bar is composed of two equal shapes: the first one creates the bar background and the second the bar fill. Changing the stroke-dashoffset and stroke-dasharray values of the second shape creates the fill effect.

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

• Set a data-progress equal to the percentage value to the .c-progress-bar element:

<div class="c-progress-bar js-c-progress-bar" data-progress="30%">
  <!-- ... -->
</div>​

• Set the text of the .js-c-progress-bar__value element equal to the fill value:

<span class="c-progress-bar__value color-primary flex items-center">
  <span class="js-c-progress-bar__value">30</span> %
</span>

• Set the text of the .js-c-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-c-progress-bar__aria-value">30%</span></p>​

If you wish to change the stroke width of the SVG shape, update the --c-progress-bar-stroke-width custom property.

Because the default stroke value of the SVG elements is currentColor, you can optionally use the color utility classes to modify the color of the bar (as well as the numeric value - see demo).

Plugin Options

The Circular Progress Bar component comes with some options:

• Animate the progress bar when it enters the viewport:  add the [data-animation="on"] attribute to the .c-progress-bar element. You can set a custom duration using the data-duration attribute (in ms); if this is not provided, the default duration will be used (1s).

<div class="c-progress-bar js-c-progress-bar text-center" data-progress="60%" data-animation="on">
  <!-- ... -->
</div>​

• Change the color of the progress bar based on the fill value: add the .c-progress-bar--color-update class to the .c-progress-bar element. Color thresholds are defined inside the .c-progress-bar--color-update class. Three thresholds have been defined but you can add as many thresholds as your project requires. Only make sure to: define a CSS variable (inside .c-progress-bar--color-update) and a CSS class (.c-progress-bar--fill-color-{n}) for each threshold and that threshold value increases with index (e.g., --c-progress-bar-color-{n+1} >  --c-progress-bar-color-{n}).

Dynamic Update

To dynamically update the value of your progress bar, use the updateProgress custom event. Here's an example of how to update the progress value:

// make sure to select the proper progress bar element - in this example we take the first available one
var cProgressBar = document.getElementsByClassName('js-c-progress-bar')[0]; 
// define the custom event 
// 1 - set the final value of the progress to 80%
// 2 - set the animation duration to 2s (this is not required)
var event = new CustomEvent('updateProgress', {detail: {value: 80, duration: 2000}});
// dispatch the event
cProgressBar.dispatchEvent(event);

Accessibility

The component includes a p.sr-only element (visually hidden) that is announced to Screen Readers. It contains a .js-c-progress-bar__aria-value element with the progress value.

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

If the progress value is dynamically updated, the value of this element is changed as well and announced to Screen Readers. 

Categories

• Data Display > Progress
• Plugins > Misc

Bug report & feedback

Component Github page ↗