Using the log role

Description

This technique demonstrates how to use the log role and describes the effect it has on browsers and assistive technology.

The log role is used to identify an element that creates a live region where new information is added in a meaningful order and old information may disappear. For example, chat logs, messaging history or an error log. In contrast to other types of live region, this role is sequentially ordered and new information is only added to the end of the log. When this role is added to an element, the browser will send out an accessible log event to assistive technology products which can then notify the user about it.

By default updates contain only the changes to the live region and these are announced when the user is idle. Where the user needs to hear the entire live region upon a change aria-atomic="true" should be set. To have announcements made as soon as possible and where the user may be interrupted, aria-live="assertive" can be set for more aggressive updates.

Possible effects on user agents and assistive technology

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

Expose the element as having a log role in the operating system's accessibility API.
Fire an accessible log 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 should announce changes inside a log when the user is idle, unless aria-live=”assertive” has been set and in which case the user may be interrupted.
Screen magnifiers may visually indicate that a log update has occurred.

Note: Opinons may differ on how assistive technology should handle this technique. The information provided above is one of those opinions and therefore not normative.

Examples

Example 1: Adding the role in the HTML code

The snippet below shows how the log role is added directly into the html source code.

<div id="liveregion" class="region" role="log"></div>

Example 2: Snippet from an example application

This snippet creates the chat log in an AJAX chat application.

<div id="chatArea" role="log">
  <ul id="chatRegion" aria-live="polite" aria-atomic="false">
    <li>Please choose a user name to begin using AJAX Chat.</li>
  </ul>
  <ul id="userListRegion" aria-live="off" aria-relevant="additions removals text">
  </ul>
</div>

Working Examples:

Notes

Using the log role on an element implies that element has aria-live="polite".
With an area that has scrolling text, such as a stock ticker, the marquee role should be used instead.

ARIA attributes used

Related ARIA techniques

marquee role

Compatibility

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

Additional resources

ARIA Best Practices – mplementing Live Regions: https://www.w3.org/TR/wai-aria-practices/#LiveRegions