Progress bars need a name

• Rule: axe/aria-progressbar-name
• Checks: ARIA progressbar nodes must have an accessible name
• WCAG: 1.1.1
• Fix class: content: A fix needs authored text.

Who it affects

• People who use a screen reader or a braille display, most of them blind.

How to fix it

A visible label or heading describes the task

Point aria-labelledby at it by its id. A progress bar does not take its name from its content, so a percentage shown inside it does not count.

<p id="upload-label">Uploading report.pdf</p>
<div role="progressbar" aria-labelledby="upload-label" aria-valuenow="40" aria-valuemin="0" aria-valuemax="100"></div>

The progress bar has no visible label

Name it with aria-label, saying what is in progress, such as “Loading search results”.

A native <progress> element would do

Use <progress> with a <label for>. Leave out value while the amount of progress is unknown, and the bar shows as indeterminate.

<label for="install-progress">Installing updates</label>
<progress id="install-progress" max="100" value="30">30%</progress>

Fixes that fail

Naming the bar for its role, such as aria-label="Progress bar"

Screen readers already announce the role. Say what is progressing: “Uploading report.pdf”.

Putting the label text inside the role="progressbar" element

A progress bar takes no name from its content, so axe still fails it and screen readers still announce an unnamed progress bar.

Hiding the bar with aria-hidden="true"

The rule no longer checks it, but screen reader users then cannot tell that work is still going on, unless a status message reports the same progress.

More on the rule

axe-core’s documentation of the rule

CORA’s fix guidance adapts content from accessibility-agents, under the MIT License: see its notice.