This is an unpublished editor’s draft that might include content that is not finalized. View the published version

Skip to content

Technique ARIA25:Using an ARIA live region to convey the status of a progress bar

About this Technique

This technique relates to 4.1.3 Status Messages (Sufficient).

This technique applies to content using WAI-ARIA.

Techniques are examples of ways to meet Web Content Accessibility Guidelines (WCAG). They are not required to meet WCAG. Content can satisfy the normative requirements of WCAG even if it does not use any of the documented techniques. See About WCAG Techniques.

Description

This technique demonstrates how to use an ARIA live region to programmatically convey the status of a file upload progress bar to assistive technologies.

Example

This example simulates the progress of uploading a document. The progress of the upload is communicated visually to the user with a progress bar. As the progress bar is updated, text is also updated in a visually hidden container. This container has an aria-live="polite" attribute. This attribute tells screen readers to announce updates made to the content of the element.

Note

The following example uses an element with a role="progressbar"attribute. The aria-valuemin, aria-valuemax, and aria-valuenow values on the progressbar component programmatically communicate the progress of the upload, but because the progressbar role is not a live region, screen readers won't announce updates to those values as they change. The use of an ARIA progress bar is not actually important for this technique – what matters is the progress being conveyed with a status message.

The following code can also be seen as a working example.

<div class="upload-container">
  <p id="upload-progress-label">Uploading document: <strong>report.pdf</strong></p>
  <div
    aria-labelledby="upload-progress-label"
    role="progressbar"
    aria-describedby="progress-text"
    aria-valuemin="0"
    aria-valuemax="100"
    aria-valuenow="0"
    id="upload-progress"></div>
    <button id="start-upload" type="button">Start Upload</button>
    <div aria-live="polite" class="visually-hidden" id="progress-text">0% complete</div>
</div>

Tests

Procedure

  1. Verify if the page contains a progress bar that dynamically changes to visually convey status information to the user.
  2. Using a screen reader, check that updates to the progress bar are conveyed to the user, without focus being moved programmatically to the progress bar/the status message

Expected Results

  • #1 and #2 are true.
Back to Top