Using the alert role

Description

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 about it. The alert role is most useful 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, local changes will not be saved

Because of its intrusive nature, the alert role must be used sparingly and only in situations where the user's immediate attention is required. Dynamic changes that are less urgent should use a less aggressive method, such as aria-live="polite" or other live region roles.

Possible effects on user agents and assistive technology 

When the alert role is added to an element, or such an element becomes visible, the user agent should do the following:

• Expose the element as having an alert role in the operating system's accessibility API.
• Fire an accessible alert event using the operating system's accessibility API if it supports it.

Assistive technology products should listen for such an event and notify the user accordingly:

• Screen readers may interrupt current output (whether it's speech or braille) and immediately announce or display the alert message.
• Screen magnifiers may visually indicate that an alert occurred and what the alert text was. 

Examples

Example 1: Adding the role in the HTML code

The snippet below shows how the alert role is added directly into the html source code. The moment the element finishes loading the screen reader should be notified of the alert. If the element was already in the original source code when the page loaded, the screen reader will announce the error immediately after announcing the page title.

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

Example 2: Dynamically adding an element with the alert role

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

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

Note: The same result can be achieved with less code when using a script library like jQuery:

$("<p role='alert'>You must agree with our terms of service to create an account.</p>").appendTo(document.body);

Example 3: Adding alert role to an existing element

Sometimes it's 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 instruction 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. The pseudo code snippet below illustrates this approach:

<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");

Example 4: Making an element with an alert role visible

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. 

Note: In most cases this approach is not recommended, because it's not ideal to hide error or alert text that is currently not applicable. Users of older assistive technology may still be able to perceive the alert text even when the alert does not currently applies, causing users to incorrectly believe that there is a problem.

.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").className = ""; 

Working Examples:

• Alert role example using an ARIA alert box
• Alert example using a modal ARIA dialog box

Notes 

• Using the alert role on an element implies that that element has aria-live="assertive".
• The alert role should only be used to for static text content. The element that the alert role is used on does not have to be able to receive focus, as screen readers will automatically announce the alert regardless of where keyboard focus is currently located.
• If an alert also provides interactive controls (such as form controls that allow the user to rectify a problem, or an "OK" button that discards the alert) the alertdialog role should be used instead. 

ARIA attributes used

• alert

Related ARIA techniques 

• Using the alertdialog role
• Using the aria-invalid property

Compatibility

TBD: Add support information for common UA and AT product combinations

Additional resources

• ARIA Best Practices - Alert Role: https://www.w3.org/TR/wai-aria-practices/#alert