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 a type of assistive tech that converts things on screen to audio and/or braille. It's important that things are understandable and interactive to screen readers.

Keyboard accessibility is essential for people who do not use a computer mouse (which might be because they have unpredictable or very specific movement due to a motor disability). Many Blind and visually impaired people also use keyboard interactions in order to use their screen reader.

Error support is accessible to people with a diversity of disabilities. A cognitive disability might affect how a person perceives and understands things. A physical disability might lead to unpredictable movement. Other factors such as environment, stress, and multi-tasking may also lead to errors.

In order to be accessible, gestures and interactions must account for people with physical and motor disabilities, who might have unpredictable or very specific movement.

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).

Level AAA compliance is considered more difficult to meet because it requires more resources to fulfill. It also might encompass conflicting access needs (meaning what is accessible to some might be inaccessible to others). Use your best judgment of your target audience and your team's capabilities to determine if this is a pragmatic goal to reach.

How to Implement This

In order to implement this rule, there are a few different ways 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.


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>

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>

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>

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

Manual Test
Semi-Automated Test
Automated Test
  • Use a screen reader to test for status messages. It's recommended to conduct user testing with a screen reader user.
  • Interact with the website/app in a way that would trigger a status message (such as submitting a form).
  • Make note if the screen reader is able to detect the status message.


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)