Content must be robust enough that it can be interpreted by a wide variety of user agents, including assistive technologies.

Guideline 4.1 - Compatible

Maximize compatibility with current and future user agents, including assistive technologies.

Success Criterion 4.1.3 - Status Messages

In content implemented using markup languages, status messages can be programmatically determined through roles or properties such that they can be presented to the user by assistive technologies without receiving focus.

A status message is a defined term in WCAG, with the definition:

change in content that is not a change of context and that provides information to the user on the success or results of an action, on the waiting state of an application, on the progress of a process, or the existence of errors

As per Understanding WCAG, two main criteria determine whether something is a status message or not:

1. the message "provides information to the user on the success or results of an action, on the waiting state of an application, on the progress of a process, or the existence of errors"
2. the message is not delivered via a change in context

A change of context is also a defined term in WCAG, referring to "major changes in the content of the Web page that, if made without user awareness, can disorient users who are not able to view the entire page simultaneously", which include changes of the user agent, viewport, focus and changes of content that change the meaning of a web page (which not all changes of content do - for instance, switching a tab on a page isn't a change of context)

The intent of this success criterion is to make users aware of important changes in content that need to be given focus and in a way that doesn't unnecessarily interrupt them. Status messages are read out by screen readers when they change, and in a way that minimizes interruptions to users, while still providing them with updates.

What are and what aren't status messages?

• If you're building a SPA that supports search or AJAX-based search, a status message could be the number of results returned after they've been fetched and rendered.
  • In this case, we imagine that after a successful search query, you'd visibly render text such as "5 results returned" and those five results.
  • The status updates such as "5 results returned", "No results found" or "Searching..." would be status messages. The result set itself would not be.
• After adding an item to a shopping cart in the web shop, a status message could indicate the change in the number of items.
• Validation messages in form fields (such as "Invalid email") are status messages.
• While not status messages explicitly, progress bars with a valid ARIA role will be periodically read out by screen readers.
• An error message displayed in a dialog that takes focus isn't a status message. Because the dialog takes focus, it's a change of context and does not meet the definition of a status message.

Implementing support for status messages

When you've identified something on your page that is a status message, you can use the following techniques depending on the situation.

If a status message advises on the success or results of an action or the state of an application:

• use role="status" to present status messages in combination with providing success feedback when data is submitted successfully

If an element with the ARIA role status is updated dynamically, assistive technologies are automatically informed of the change and can present it to the user.

<a href="/cart" class="cart-button" role="status">
 <img src="assets/cart.svg" alt="Shopping cart">
 <span id="cart-count">5</span> items
</a>

function addToCart (item) {
 // ...
 const cartCount = parseInt(document.querySelector('#cart-count').innerHTML);
 document.querySelector('#cart-count').innerHTML = cartCount + 1;
}

If a status message conveys a suggestion or a warning on the existence of an error:

• use role="alert" or ARIA live regions to identify errors in combination with:
  • providing text descriptions to identify required fields that were not completed
  • providing a text description when validation fails
  • providing suggested corrections and suggestions

Note that the alert role will interrupt the user on content changes.

<!-- aria-atomic is used for VoiceOver support, see Understanding WCAG link -->
<p id="errors" role="alert" aria-atomic="true"></p>

function handleError (errorText) {
 document.querySelector('#errors').append(errorText);
}

Using ARIA live regions, you can mark whole regions as live and make screen readers and other assistive technologies announce changes in them automatically. To mark a region as live, use aria-live="polite" or aria-live="assertive". Note that polite waits for the user to be idle, while assertive interrupts any announcement in progress and is disruptive to users. Therefore, assertive should be used only for time-sensitive and critical notifications that require the user's immediate attention.

For more information on using ARIA live regions, refer to the MDN article on ARIA live regions.

If a status message conveys information on the progress of a process:

• use role="log" to identify sequential information updates, such as a chat conversation or activity log
• use role="progressbar on progressbars

Similar implementations apply here: after defining a live role on an element, updating its content will be announced by assistive technologies.

Notes

The roles log, status, alert, progressbar, marquee and timer implicitly define aria-live (as polite for all of them, apart from alert, which is assertive by default). Therefore, user agents interpret them as special cases of live regions. Setting aria-live on them is redundant and, in some cases, may cause double announcements.

You can fail this success criterion if:

• you misuse aria-live="assertive" or aria-live="alert" for non-critical updates
• provide status messages without using ARIA to mark them as live by using roles or attributes

Learn more about ARIA live regions on MDN and [find more techniques, failures]