Progress Bar

Provide up-to-date feedback on the progress of a workflow or action with simple progress bars.

25%

Basic usage

Twig

{{
  html.progress({
    'value': 25,
    'aria-label': 'File upload progress'
  })
}}

HTML

<div className="progress">
  <div 
    aria-label="File upload progress" 
    role="progressbar" 
    aria-valuenow="25" 
    aria-valuemin="0" 
    aria-valuemax="100" 
    style="width: 25%" 
    className="progress-bar"
  >
    <span className="hide">25%</span>
  </div>
</div>

Helper options

You can configure this helper using the common helper options, the following options are specific to this helper.

Option	Type	Description
label	string	An optional text label to display inside the progress bar
value	integer	The percentage value of the progress bar (without the % symbol)
value_visible	bool	If true, shows the value percentage (with % symbol) in the progress bar

Accessibility

To ensure screen readers users are able to discern the purpose of elements with role="progressbar" an accessible name must be used. This can be via aria-label or if another visible element exists as a title for the progress bar, aria-labelledby.

Updating progress with JavaScript

Given the rendered markup example below, you’ll need to write code to update the two main percentage values in aria-valuenow and the inline style attribute with your new percentage. If you have the percentage in the label either hidden or visible then you’ll need to update that too.

You should also add a live region to the DOM, which your code updates to communicate progress updates to screen reader users.

For example: when loading <span id="progress-live-region" class="hide" aria-live="polite">23%</span> and when completed <span id="progress-live-region" class="hide" aria-live="polite">loading complete</span>.

25%

25%

<div className="progress">
  <div
    className="progress-bar"
    role="progressbar"
    aria-label="File upload progress"
    aria-valuenow="25"
    aria-valuemin="0"
    aria-valuemax="100"
    style={{'width': '25%'}}
  >
    25%
  </div>
</div>
<span id="progress-live-region" className="hide" aria-live="polite">25%</span>

States

Use the common state variation classes to help communicate progress, or lack of it. Showing visible labels can help to show the precise progress or show other relevant updates.

Base

25%

Twig

{{
  html.progress({
    'value': 25,
    'aria-label': 'File upload progress'
  })
}}

HTML

<div class="progress">
  <div 
    aria-label="File upload progress" 
    role="progressbar" 
    aria-valuenow="25" 
    aria-valuemin="0" 
    aria-valuemax="100" 
    style="width: 25%" 
    class="progress-bar"
  >25%</div>
</div>

25%

Twig

{{
  html.progress({
    'value': 25,
    'aria-label': 'File upload progress'
  })
}}

HTML

<div class="progress">
  <div 
    aria-label="File upload progress" 
    role="progressbar" 
    aria-valuenow="25" 
    aria-valuemin="0" 
    aria-valuemax="100" 
    style="width: 25%" 
    class="progress-bar"
  >25%</div>
</div>

Warning

33% Having trouble connecting…

Twig

{{
  html.progress({
    'label': 'Having trouble connecting…',
    'aria-label': 'File upload progress',
    'value': 33,
    'value_visible': true,
    'class': 'progress-bar--warning'
  })
}}

HTML

<div class="progress">
  <div 
    aria-label="File upload progress" 
    role="progressbar" 
    aria-valuenow="33" 
    aria-valuemin="0" 
    aria-valuemax="100" 
    style="width: 33%;" 
    class="progress-bar progress-bar--warning"
  >33% Having trouble connecting&hellip;</div>
</div>

Danger

75% Upload failed

Twig

{{
  html.progress({
    'label': 'Upload failed ' ~ html.icon('warning-sign'),
    'aria-label': 'File upload progress',
    'value': 75,
    'class': 'progress-bar--danger'
  })
}}

HTML

<div class="progress">
  <div 
    aria-label="File upload progress" 
    role="progressbar" 
    aria-valuenow="75" 
    aria-valuemin="0" 
    aria-valuemax="100" 
    style="width: 75%;" 
    class="progress-bar progress-bar--danger"
  ><span class="hide">75%</span> Upload failed <i aria-hidden="true"  class="icon-warning-sign"></i>
  </div>
</div>

Success

100% Uploaded

Twig

{{
  html.progress({
    'label': 'Uploaded ' ~ html.icon('ok'),
    'aria-label': 'File upload progress',
    'value': 100,
    'class': 'progress-bar--success'
  })
}}

HTML

<div class="progress">
  <div 
    aria-label="File upload progress" 
    role="progressbar" 
    aria-valuenow="100" 
    aria-valuemin="0" 
    aria-valuemax="100" 
    style="width: 100%;" 
    class="progress-bar progress-bar--success"
  >
    <span class="hide">100%</span> Uploaded <i aria-hidden="true"  class="icon-ok"></i>
  </div>
</div>