ARIA: alert role

The alert role is for important, and usually time-sensitive, information. The alert is a type of status processed as an atomic live region.

The alert role is used to communicate an important and usually time-sensitive message to the user. When this role is added to an element, the browser will send out an accessible alert event to assistive technology products which can then notify the user.

The alert role should only be used for information that requires the user's immediate attention, for example:

• An invalid value was entered into a form field
• The user's login session is about to expire
• The connection to the server was lost so local changes will not be saved

The alert role should only be used for text content, not interactive elements such as links or buttons. The element with the alert role does not have to be able to receive focus, as screen readers (speech or braille) will automatically announce the updated content regardless of where keyboard focus when the role is added.

The alert role is added to the node containing an alert message, not the element causing the alert to be triggered. Alerts are assertive live regions. Setting role="alert" is equivalent to setting aria-live="assertive" and aria-atomic="true". As they don't receive focus, focus does not need to be managed and no user interaction should be required.

The alert role is of the five live region roles. Dynamic changes that are less urgent should use a less aggressive method, such as including aria-live="polite" or using an other live region role like status. If the user is expected to close the alert, then the alertdialog role should be used instead.

The most important thing to know about the alert role is that it's for content that is dynamically displayed, not for content that appears on page load. It is perfect for situations such as when a user fills out a form and JavaScript is used to add an error message - the alert would immediately read out the message. It should not be used on HTML that the user hasn't interacted with. For example, if a page loads with multiple visible alerts scattered throughout, the alert role should not be used, as the messages were not dynamically triggered.

If an element has role="alert" and display: none; set, when the display value is changed with CSS or JavaScript, it automatically triggers the screen reader to read out the content.

<p role="alert" style="display: none;">This alert will trigger when the element becomes visible.</p>

While triggering an alert via CSS alone is possible, it is better to rely on JavaScript because it has more browser/screen reader support and is often more appropriate as part of a larger user interaction, such as inside an event handler or form validation.

With JavaScript, developers control the adding and removing of alerts as appropriate.

<button type="button">Trigger alert</button>
<p class="alert">The alert will trigger when the button is pressed.</p>

const btn = document.querySelector('button');
btn.addEventListener('click', triggerAlert);

function triggerAlert() {
  var alertEl = document.querySelector('.alert');
  alertEl.setAttribute("role", "alert");
}

As the alert role reads out content that has changed, bring the user's attention to it immediately, it should not be used for static content nor used regularly. Alerts, by definition, are disruptive. Several alerts at once, and unnecessary alerts, create bad user experiences.

Following are four ways of creating alerts:

Here, the alert role is added directly into the HTML source code. When the element finishes loading the screen reader will be notified of the alert.

<h2 role="alert">Your form could not be submitted because of 3 validation errors.</h2>

If the element is in the original source code when the page loads, the screen reader will announce the error immediately after announcing the page title.

This snippet dynamically creates an element with an alert role and adds it to the document structure.

let myAlert = document.createElement("p");
myAlert.setAttribute("role", "alert");
let myAlertText = document.createTextNode("You must agree with our terms of service to create an account.");
myAlert.appendChild(myAlertText);
document.body.appendChild(myAlert);

Sometimes it is useful to add an alert role to an element that is already visible on the page rather than creating a new element. This allows the developer to reiterate information that has become more relevant or urgent to the user. For example, a form control may have instructions about the expected value. If a different value is entered, role="alert" can be added to the instruction text so that the screen reader announces it as an alert.

<p id="formInstruction">You must select at least 3 options</p>

// When the user tries to submit the form with less than 3 checkboxes selected:
document.getElementById("formInstruction").setAttribute("role", "alert");

If an element already has role="alert" and is initially hidden using CSS, making it visible will cause the alert to fire as if it was just added to the page. This means that an existing alert can be "reused" multiple times.

.hidden {
  display:none;
}

<p id="expirationWarning" role="alert" class="hidden">Your log in session will expire in 2 minutes</p>

// removing the 'hidden' class makes the element visible, which will make the screen reader announce the alert:
document.getElementById("expirationWarning").classList.remove('hidden'); 

• aria-live
• aria-atomic
• ARIA: log role
• ARIA: marquee role
• ARIA: status role
• ARIA: timer role
• ARIA: alertdialog role
• ARIA: live regions
• ARIA alert support - The Paciello Group
• ARIA Practices alert example