# Using ARIA role=alert or Live Regions to Identify Errors

ID: ARIA19

Technology: aria

Type: Technique

## When to Use

Technologies that support Accessible Rich Internet Applications (WAI-ARIA).

## Description

The purpose of this technique is to notify Assistive Technologies (AT) when an input error occurs. The `aria-live` attribute makes it possible for an AT (such as a screen reader) to be notified when error messages are injected into a Live Region container. The content within the `aria-live` region is automatically read by the AT, without the AT having to focus on the place where the text is displayed.

There are also a number of special case live region roles which can be used instead of applying live region properties directly.

## Examples

### Injecting error messages into a container with role=alert already present in the DOM

The following example uses role=alert which is equivalent to using aria-live=assertive.

In the example there is an empty error message container element with aria-atomic=true and an aria-live property or alert role present in the DOM on page load. The error container must be present in the DOM on page load for the error message to be spoken by most screen readers. aria-atomic=true is necessary to make Voiceover on iOS read the error messages after more than one invalid submission.

jQuery is used to test if the inputs are empty on submit and inject error messages into the live region containers if so. Each time a new submit is attempted the previous error messages are removed from the container and new error messages injected.

    $(document).ready(function(e) {
      $('#signup').submit(function() {
        $('#errors').html('');
        if ($('#first').val() === '') {
          $('#errors').append('<p>Please enter your first name.</p>');
        }
        if ($('#last').val() === '') {
          $('#errors').append('<p>Please enter your last name.</p>');
        }
        if ($('#email').val() === '') {
          $('#errors').append('<p>Please enter your email address.</p>');
        }
        return false;
      });
    });
    <form name="signup" id="signup">
      <p id="errors" role="alert" aria-atomic="true"></p>
      <div>
        <label for="first">First Name (required)</label><br>
        <input type="text" name="first" id="first">
      </div>
      <div>
        <label for="last">Last Name (required)</label><br>
        <input type="text" name="last" id="last">
      </div>
      <div>
        <label for="email">Email (required)</label><br>
        <input type="text" name="email" id="email">
      </div>
      <div>
        <input type="submit" name="button" id="button" value="Submit">
      </div>
     </form>

Working example: Using role=alert to identify errors.

## Tests

### Procedure

1. Determine that an empty error container `role=alert` or `aria-live=assertive` attribute is present in the DOM at page load.
2. Trigger the error that causes the content in the live region to appear or update.
3. Determine that the error message was injected into the already present error container.

### Expected Results

- #1 and #3 are true.

## Related Techniques

## Resources

- WAI-ARIA Authoring Practices Guide
- HTML5 Accessibility Chops: ARIA role=alert browser support
- WAI-ARIA, Supported States and Properties, aria-describedby
- WAI-ARIA, The Roles model, alert