ARIA: progressbar role

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

Description

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

Authors may 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">:

If the progressbar role is applied to an HTML <progress> element, the accessible name can come from the associated <label>. Otherwise use aria-labelledby if a visible label is present or aria-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 a progressbar. To deal with this limitation, browsers, automatically apply role presentation to all descendant elements of any progressbar element as it is a role that does not support semantic children.

For example, consider the following progressbar element, which contains a heading.

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

Because descendants of progressbar 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 the accessibility 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 between 0, or aria-valuemin if present, and aria-valuemax indicating the current value of the progress bar.

aria-valuetext

Assistive technologies often present the value of aria-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 than aria-valuemax. If not present, the default value is 0.

aria-valuemax

Set to a decimal value representing the maximum value, and greater than aria-valuemin. If not present, the default value is 100.

aria-label or aria-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 the progressbar role. User agents provide a stylize widget for the <progress> element based on the current value as it relates to the 0, the minimum value, and the max 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 for aria-valuemin and aria-valuemax:

html
<div>
  <span id="loadinglabel">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 id="loadinglabel" max="100" value="23"></progress>

Best practices

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

Prefer HTML

It is recommended to use a native <progress> or <input type="range"> elements rather than the progressbar role.

Specifications

See also