Using ARIA role=alert or Live Regions to Identify Errors

From WCAG WG

Status

TF feedback:

  • Removed 2 of the 3 examples and added some text to description during 9/12/2013 TF Meeting
  • Paul to change title of linked page to "Using ARIA Live Regions or role=alert to Identify Errors" and remove 2 other examples.

Live examples to be moved to W3C space when technique is published. Hosted on Paul's web site for development.

  • Added to XML by AWK 2014/1/3

User Agent Notes [To be published separately]

Supports this technique:

  • OS X 10.8.4 + Safari + VoiceOver
  • iOS 6 & 7 + Mobile Safari + VoiceOver
  • Windows 7 + Firefox 20 + NVDA 2013.1
  • Windows 7 + Firefox 20 + JAWS 14
  • Windows 7 + IE 8 + JAWS 14 (aria-live=assertive ONLY)
  • Windows 7 + IE 7 + JAWS 14 (aria-live=assertive ONLY)

Does NOT support this technique:

  • Windows 7 + IE 8 + NVDA 2013.1 (NO support)

Support Notes:

When using Firefox with JAWS and NVDA role=alert is announced as "Alert" and aria-live=assertive does not include that extra text. There is NO support for NVDA 2013.1 + IE 8. The third example uses BOTH role=alert & aria-live=assertive on the error container for wider UA/AT support working in all combinations listed.

There are different methods to display an alert or assertive live region on the page and depending on how you create the error container or inject the error messages determines if it will work in the more difficult browsers/screen reader combinations like IE 8 + JAWS 14 or VoiceOver + Safari.

Applicability

This technique applies to HTML with WAI-ARIA.

This technique relates to Success Criterion (SC) 3.3.1. (Error identification):

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

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.

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

<script src="http://code.jquery.com/jquery.js"></script>
<script>
$(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;
	});
});
</script>

<form name="signup" id="signup" method="post" action="">
  <p id="errors" role="alert" aria-atomic="true"></p>
  <p>
    <label for="first">First Name (required)</label><br>
    <input type="text" name="first" id="first">
  </p>
  <p>
    <label for="last">Last Name (required)</label><br>
    <input type="text" name="last" id="last">
  </p>
  <p>
    <label for="email">Email (required)</label><br>
    <input type="text" name="email" id="email">
  </p>
  <p>
    <input type="submit" name="button" id="button" value="Submit">
  </p>
</form>

A live example of the code can be used to demonstrate the differences in browser/AT support for this technology.

Resources

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

  • Check that #1 and #3 are true.
Retrieved from "https://www.w3.org/WAI/GL/wiki/index.php?title=Using_ARIA_role%3Dalert_or_Live_Regions_to_Identify_Errors&oldid=3743"