Define status messages in markup

Code with a banner above
Image description: graphic illustration of a dark purple code editor in a web browser. Above the browser is a light red banner that says, "Something went wrong!" with a "x" close button. The code snippet below shows the code in the illustration.

<div class=”error” tabindex=”-1” aria-labelledby=”error-title”> <h1 id=”error-title”>Something went wrong!</h1> </div>

This page is in progress -

If you would like to contribute or make a case to prioritize this page, please fill out the form below.

Why This is Important

Status messages must be available to screen readers so that Blind and visually impaired people can access timely information.

Blind and visually impaired people use screen readers to interact with websites and apps. A screen reader is an assistive technology that converts text, buttons, and other screen elements to audio and/or braille. Learn more about how screen readers work.

A status message (sometimes called a banner, notification, or toast) is a UI element that relays important information to the user in a time-sensitive manner. If it is not detectable by a screen reader, then that information is unavailable.

This references WCAG criterion 4.3.1 Status Messages (Level AA).

How to Implement This

There are a few different ways to implement this rule that you can choose from based on personal preference and/or what best suits your system.

Tabindex Attribute

You can set the tabindex attribute to “-1” so that the status message is automatically focused with Javascript.

tabindex="-1"

The tab index attribute should be part of the surrounding div.

<div class=”error” tabindex=”-1” aria-labelledby=”error-title”>
<h1 id=”error-title”>Something went wrong!</h1>
</div>

Role Attribute

You can set the role attribute to “status” or “alert” to inform screen readers about the nature of the status message. “Status” is considered less critical while “alerts” should be used to communicate greater urgency.

<div class=”error” role=”alert” aria-labelledby=”error-title”>
<h1 id=”error-title”>Something went wrong!</h1>
</div>

ARIA Live Region

You can set the aria-live attribute to “polite” or “assertive” to announce dynamic changes in the content of a live region. For example, the aria-live attribute is being used on the form below! The error and success messages following a form submission are labeled as:

<div class=”error” aria-live="polite" aria-labelledby=”error-title”>
<h1 id=”error-title”>Something went wrong!</h1>
</div>


Similar to status vs. alerts, “polite” is more for updates while “assertive” is for critical information that require immediate attention.

Interesting further reading


How to Test This

This requires manual testing with a screen reader. Interact with the application to trigger a status message and see if the screen reader is able to detect it.

Credits

No credits yet. But this could be you!

Code snippets written by Michellanne Li.

Documentation and reading suggestions by Michellanne Li.

Contribute and Give Feedback

If you would like to provide feedback or contribute content on this resource, please fill out the form below.

Thank you, your submission has been received!
Oops! Something went wrong while submitting the form. Please check your internet connection and try again.

If you continue to encounter issues, please reach out to alexyingchen(at)gmail.com.