Accessible Publishing Knowledge Base

Live Regions

Summary

...

Techniques

Scripting changes to the DOM can dynamically change the text. While sighted users may see such changes, they may not be presented to users using assistive technologies. An assistive technology will typically build its own copy of the DOM to operate on, so unless you alert it of a change, the new information will not be made available.

Creating a live region

To solve this problem, the WAI-ARIA specification includes the aria-live attribute. When set, this attribute indicates that text is expected to be dynamically written to the element, ensuring that when changes do occur they get picked up by the assistive technology.

<div
    id="results"
    aria-live="assertive"/>

When the attribute is set to the value assertive it indicates that changes should be announced to the user as soon as they are written. When set to polite, changes should be announced to the user during an idle period.

Controlling playback

It's not always the case that you want updates read as they happen. The aria-busy attribute can be used to tell the reading system to wait before announcing changes to the user. Set the attribute to true before writing. The reading system will wait until the attribute is changed back to false before announcing the changes.

<div
    id="results"
    aria-live="assertive"
    aria-busy="false"/>

Controlling what's read

WAI-ARIA also includes the aria-atomic attribute for further control over what gets read. When set to true, all text inside the element gets read regardless of what has been updated. When set to false, the reading system will only read the changed text.

<div
    id="results"
    aria-live="assertive"
    aria-busy="false"
    aria-atomic="true"/>

Controlling what gets noticed

The aria-relevant attribute can be used to control the type of updates to read: element additions (additions), element deletions (removals), text changes (text) or all changes (all).

<div
    id="results"
    aria-live="assertive"
    aria-busy="false"
    aria-atomic="true"
    aria-relevant="all"/>

Default live regions

Setting any of the following values for an element's role attribute automatically makes them live: alert, log, marguee, status and timer.

<div
    id="results"
    role="alert"/>

Example

Example 1 — A simple form that display the result
<form>
   <div>
     What is the capital of Sweden?
     
     <label for="q1a">
       <input
            type="radio"
            id="q1a"
            name="q1"/>a. Innsbruck
     </label>
     
     <label for="q1b">
       <input
            type="radio"
            id="q1b"
            name="q1"/>b. Oslo
     </label>
     
     <label for="q1c">
       <input
            type="radio"
            id="q1c"
            name="q1"/>c. Stockholm
     </label>
     
     <label for="q1d">
       <input
            type="radio"
            id="q1d"
            name="q1"/>d. Uppsala
     </label>
   </div>
   
   <input
        type="button"
        value="Verify"
        onclick="checkAnswers()"/>
</form>

<div
    id="result"
    aria-live="assertive"
    aria-atomic="true"
    hidden="hidden">
   Your answer is <span id="answer"/>!
</div>

<script type="text/javascript">
<![CDATA[

function checkAnswers() {
   var q1ans = document.getElementById('q1-answer');

   while (q1ans.hasChildNodes()) {
     q1ans.removeChild(q1ans.firstChild);
   }
   
   var response = document.getElementById('q1c').checked ? 'correct' : 'incorrect';
   
   q1ans.appendChild(document.createTextNode(response));
   q1ans.className = response;
   
   var result = document.getElementById('result');
   
   result.removeAttribute('hidden');
}

]]>
</script>

A working example of this code follows.

What is the capital of Sweden?

References