ARIA: progressbar role

Theprogressbar role defines an element that displays the progress status for tasks that take a long time.

Description

Theprogressbar range widget indicates that a request has been received and the application is making progress toward completing the requested action.

Authorsmay set aria-valuemin and aria-valuemax to indicate the minimum and maximum progress indicator values. Otherwise, their implicit values follow the same rules as HTML's<input type="range">:

Ifaria-valuemin is missing or not a number, it defaults to0 (zero).
Ifaria-valuemax is missing or not a number, it defaults to100.
Thearia-valuemin andaria-valuemax properties only need to be set for theprogressbar role when the progress bar's minimum is not0 or the maximum value is not100.
The read-onlyaria-valuenow should be provided and updated unless the value isindeterminate, in which case don't include the attribute. If set, make sure thearia-valuenow value is between the minimum and maximum values.

If theprogressbar role is applied to an HTML<progress> element, the accessible name can come from the associated<label>. Otherwise usearia-labelledby if a visible label is present oraria-label if a visible label is not present.

All descendants are presentational

There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in aprogressbar. To deal with this limitation, browsers, automatically apply rolepresentation to all descendant elements of anyprogressbar element as it is a role that does not support semantic children.

For example, consider the followingprogressbar element, which contains a heading.

html

<div role="progressbar"><h3>Title of my progressbar</h3></div>

Because descendants ofprogressbar are presentational, the following code is equivalent:

html

<div role="progressbar">  <h3 role="presentation">Title of my progressbar</h3></div>

From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in theaccessibility tree:

html

<div role="progressbar">Title of my progressbar</div>

Associated WAI-ARIA roles, states, and properties

aria-valuenow: Only present and required if the value is not indeterminate. Set to a decimal value between0, oraria-valuemin if present, andaria-valuemax indicating the current value of the progress bar.
aria-valuetext: Assistive technologies often present the value ofaria-valuenow as a percentage. If this would not be accurate use this property to make the progress bar value understandable.
aria-valuemin: Set to a decimal value representing the minimum value, and less thanaria-valuemax. If not present, the default value is0.
aria-valuemax: Set to a decimal value representing the maximum value, and greater thanaria-valuemin. If not present, the default value is100.
aria-label oraria-labelledby: Defines the string value or identifies the element (or elements) that label the progressbar element providing an accessible name. An accessible name is required.

It is recommended to use a native<progress> or<input type="range"> elements rather than theprogressbar role. User agents provide a stylize widget for the<progress> element based on the currentvalue as it relates to the0, the minimum value, and themax value. When using non-semantic elements, all features of the native semantic element need to be recreated with ARIA attributes, JavaScript and CSS.

Examples

In the example below, the progress bar uses the default values of 0 and 100 foraria-valuemin andaria-valuemax:

html

<div>  <span>Loading:</span>  <span role="progressbar" aria-labelledby="loadinglabel" aria-valuenow="23">    <svg width="100" height="10">      <rect height="10" width="100" stroke="black" fill="black" />      <rect height="10" width="23" fill="white" />    </svg>  </span></div>

Using semantic HTML, this could be written as:

html

<label for="loadinglabel">Loading:</label><progress max="100" value="23"></progress>

Best practices

If the progress bar is describing the loading progress of a particular region of a page, include thearia-describedby attribute to reference the progress bar's status, and set thearia-busy attribute totrue on the region until it is finished loading.