Using the progressbar role - Accessibility 编辑

This technique demonstrates how to use the progressbar role and describes the effect it has on browsers and assistive technology.

The progressbar role should be used for an element that displays the progress status for a task that take a long time or consists of several steps.

A progressbar indicates that the user's request has been received and the application is making progress toward completing the requested action. If the actual value of the progressbar can be determined, the developer has to indicate this progress using the aria-valuenow, aria-valuemin, and aria-valuemax attributes. If the progress value  is indeterminate, the developer should omit the aria-valuenow attribute.

As the task progresses, the aria-valuenow value has to be updated dynamically to indicate this progress to assistive technology products. 

If the progressbar is describing the loading progress of a particular region of a page, the author SHOULD use aria-describedby to point to the status, and set the aria-busy attribute to true on the region until it is finished loading. It is not possible for the user to alter the value of a progressbar because it is always readonly.

Note: Assistive technologies generally will render the value of aria-valuenow as a percent of the range between the value of aria-valuemin and aria-valuemax, unless aria-valuetext is specified. It is best to set the values for aria-valuemin, aria-valuemax, and aria-valuenow in a manner that is appropriate for this calculation. Note: Elements with the role progressbar have an implicit aria-readonly value of true.

Possible effects on user agents and assistive technology 

Screen readers should announce the progress updates as they occur. If the progress bar is labeled, the label text should be mentioned as well.

Note: Opinions may differ on how assistive technology should handle this. The information provided above is one of those opinions and therefore not normative.

Examples

Example 1: Basic progressbar with percentage values

<div role="progressbar" aria-valuenow="20" aria-valuemin="0" aria-valuemax="100">20 %</div>

Example 2: Using aria-valuetext 

<div role="progressbar" aria-valuenow="20" aria-valuemin="0" aria-valuetext="Step 2: Copying files... " aria-valuemax="100">
  Step 2: Copying files...
</div>

Working Examples:

Notes 

ARIA attributes used

• progressbar
• aria-valuenow
• aria-valuemin
• aria-valuemax
• aria-valuetext

Related ARIA techniques 

Compatibility

TBD: Add support information for common UA and AT product combinations

Additional resources