Progress Bar
- Central CMS
- Central Forms
- Central Connect
Provide up-to-date feedback on the progress of a workflow or action with simple progress bars.
Basic usage
- Twig
- HTML
{{
html.progress({
'value': 25,
'aria-label': 'File upload progress'
})
}}
<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>
.
<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
- Twig
- HTML
{{
html.progress({
'value': 25,
'aria-label': 'File upload progress'
})
}}
<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>
- Twig
- HTML
{{
html.progress({
'value': 25,
'aria-label': 'File upload progress'
})
}}
<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
- Twig
- HTML
{{
html.progress({
'label': 'Having trouble connecting…',
'aria-label': 'File upload progress',
'value': 33,
'value_visible': true,
'class': 'progress-bar--warning'
})
}}
<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…</div>
</div>
Danger
- Twig
- HTML
{{
html.progress({
'label': 'Upload failed ' ~ html.icon('warning-sign'),
'aria-label': 'File upload progress',
'value': 75,
'class': 'progress-bar--danger'
})
}}
<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
- Twig
- HTML
{{
html.progress({
'label': 'Uploaded ' ~ html.icon('ok'),
'aria-label': 'File upload progress',
'value': 100,
'class': 'progress-bar--success'
})
}}
<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>