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.

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