WAI-ARIA Live Regions Updated

Monday, 14th January 2013

Author: Gez Lemon

Rich Internet Applications

When developers first built rich internet applications using a combination of HTML, CSS, and JavaScript, people with disabilities were left behind because those applications failed to provide the semantics required to be understood by assistive technologies. Sadly, not much has changed over the years, but that doesn't need to be the case. WAI-ARIA is capable of providing sufficient semantics to ensure rich internet applications can be understood, and is now relatively well supported.

A significant issue that the WAI-ARIA specification addresses is where parts of the page are updated without informing assistive technology users, using live regions.

Live Regions

Live regions inform assistive technology users of updates in the document without the user losing focus from their current activity. For example, announcing changes in a table that is dynamically updated with stock information. Live regions can also be used to aid the understanding of complex widgets. For example, Hans Hillen uses a hidden live region to announce how many items are returned in his example of an auto-complete widget, along with instructions to use the cursor keys to navigate through the list, as support for autocomplete isn't that good without this context at the moment. The following properties are used to define a live region.

The aria-live property

The aria-live property indicates a section within the content that is live and the verbosity in which changes shall be announced. The following values may be used to determine the verbosity.

aria-live="off"

The default value that indicates that a region is not live, and changes will not be announced.

aria-live="polite"

The update should be announced at the next graceful interval, such as when the user stops typing.

aria-live="assertive"

The update is announced to the user immediately. As this is obtrusive, a value of assertive should only be used when the update is important and the user should be informed immediately.

In the following example, text changes or additions to the unordered list, they will be announced to the user.

<ul aria-live="polite">
  <li>Item 1</li>
  <li>Item 2</li>
  <li>item 3</li>
</ul>

The aria-atomic property

The aria-atomic property is an optional property that can have the values true or false (default). When the region is updated, the atomic property is used to indicate if assistive technologies should present all or part of the changed region to the user, and is influenced by the aria-relevant property. If the aria-atomic property is set to true, assistive technologies should present the entire region as a whole depending on the aria-relevant property; otherwise, the part of the region that changed might be announced on its own.

Sometimes, updates make sense on their own, such as a new line arriving in a chat application. Other times, changes in the content may not make sense without the context of other parts of the region. In these cases, aria-atomic="true" should be set on the relevant container so the region is presented as a whole. In the following example, if a change is made anywhere in the div element, the whole content is announced to the user.

<div aria-live="polite" 
    aria-atomic="true">
  <h3>Currently playing</h3>
  <p>Jake Bugg - Lightening Bolt</p>
</div>

The aria-relevant property

The aria-relevant property is an optional property used to indicate the type of update that should be announced within a region: see changes to document content or node visibility for technical details. The aria-relevant property accepts a space separated list of the following property values:

aria-relevant="additions"

Announcements are made when elements are added to the DOM within the region or the CSS display state reveals hidden text in the region.

aria-relevant="removals"

Announcements are made when elements are removed from the DOM within the region or the CSS display state hides text in the region.

aria-relevant="text"

Announcements are made when text is added or removed from the DOM or the CSS display state changes.

aria-relevant="all"

All of the above (additions, removals, text) apply to this region.

In the absence of an explicit aria-relevant property, the default is to assume there are text changes and additions (aria-relevant="text additions"). In the following example, only additions to the unordered list will be announced to the user.

<ul aria-live="polite" 
    aria-relevant="additions">
  <li>Item 1</li>
  <li>Item 2</li>
  <li>item 3</li>
</ul>

The aria-busy property

The aria-busy property should be used when the region is busily being updated, and stops updates being announced before they are complete. Setting aria-busy="true" on the region suppresses announcements until the attribute is removed, or the value changed to false. Assistive technologies collate the changes, and announce them when the region is no longer busy. In the following example, nothing is announced while the list items for the unordered list are being gathered. When the developer set aria-busy="false" or removes the aria-busy attribute, the unordered list will be announced.

<ol aria-live="polite" 
    aria-busy="true">
⋯
</ol>

Roles with live regions

WAI-ARIA also defines some roles that have live regions.

The alert role

The alert role is used to provide important information immediately to the user. A role of alert is an assertive live region, meaning the message will be delivered to the user immediately.

<div role="alert">
  Maximum amount reached.
</div>

The status role

The status role is used to provide advisory information to the user that isn't important enough for an alert. A role of status has an implicit aria-live value of polite, but this doesn't necessarily mean it will be announced to the user. Authors can use the aria-live property on the region to override how it's usually handled by assistive technologies.

<div role="status">
  3 new messages in inbox.
</div>

The timer role

The timer role marks a region that contains a counter that represents either elapsed or remaining time that are updated as time changes until the timer is paused or completes the time count. A role of timer is a live region with an implied aria-live value of off.

<div role="timer">
  29
</div>

The marquee role

The marquee role is used when non-essential information changes regularly. A role of marquee is a live region with an implied aria-live value of off. If you use marquees, ensure you provide a simple provision to stop it scrolling and updating, as they can be distracting and annoying.

<div role="marquee">
  Marquee text.
</div>

The log role

The log role is used for regions where new messages are added at the end of the log, and older messages may disappear from the log, such as a chat log or messages in an error console. A role of log has an implicit aria-live value of polite. If a text area is used to send updates to the region with a role of log, the aria-controls attribute should be used to define the relationship.

<div role="log" id="chatarea">
  <span class="name">Dave: </span> What time will you be finished?
</div>
⋯
<div>
  <label for="chat">Chat: </label>
  <input aria-controls="chatarea"
         type="text" 
         size="40" 
         name="chat" 
         id="chat">
</div>

For further information about using WAI-ARIA's live regions, see the authoring practices guide for WAI-ARIA on managing dynamic changes.

Category: Accessibility.