Make webpages with partial dynamic content update accessible

by Content Team

12 January 2024

Tutorials

How to make a webpage with partial dynamic content update accessible via HTML5 ARIA live!

In this tutorial, we want to notify users when parts of the web page are dynamically updating. It is a great tool for making your web pages accessible. We achieve our goal by using HTML5 aria-live attribute.

ARIA Live Attribute Overview

Using JavaScript, it is possible to dynamically change parts of a page without requiring the entire page to reload — for instance, to update a list of search results on the fly, or to display a discreet alert or notification which does not require user interaction. While these changes are usually visually apparent to users who can see the page, they may not be obvious to users of assistive technologies. ARIA live regions fill this gap and provide a way to programmatically expose dynamic content changes in a way that can be announced by assistive technologies.

Step-by-step Implementation

First, assign the aria-live attribute to the HTML element where a content change or update may occur and decide on the urgency of communicating the update.
Then, select a standard live region role. Assign the role to the parent HTML element that contains the content that may change. If the default behaviors for the role are appropriate, you do not need to specify attributes:
<div role=”alert”>

The standard live region roles include:

alert
- Use this for a single, time-sensitive notification. It will be handled as an assertive live region and the update will appear immediately. An alert cannot receive focus, and therefore cannot be closed by the user.
alertdialog
- This type of alert message can receive focus. When the alert appears, you must automatically set focus on an active element in the alert dialog, such as an “OK” button. Include the aria-described by attribute on that active element to point to the message in the dialog.
log
- Use this for things like message history or error logs: new information is added to the end of the log, and the oldest information may disappear.
marquee
- Use this for things like stock tickers or ad banners. This is similar to a log because the information presented may change frequently.
status
- Use this for a minor notification that does not warrant use of an alert. It will be handled as an assertive live region. A status should not receive focus. If a different part of the page drives the status changes, use the aria-controls attribute to identify the relationship.
timer
- Use this to display time elapsed or remaining. Update the timer at fixed intervals, unless the timer is paused or has reached the end of its count.

If you need something other than the standard ARIA live region roles and behaviors, you can create a custom live region.

Custom live regions

First, identify where a content change or update may occur and decide how urgently the update needs to be communicated.
Next, assign the aria-live attribute to the parent HTML element that contains the content that may change. The value for the aria-live attribute will reflect how quickly the update will be communicated to users. The available values are:

aria-live=”off”, where the update is not announced
aria-live=”polite”, where the update is announced when the user is idle or finishes with his current activity
aria-live=”assertive”, where the update is announced as soon as possible, even if it means interrupting the user’s current task

Stay away from aria-live=”assertive” unless it is critical to communicate the change immediately. Users may consider the disruption jarring and rude.

As in a polite conversation where people wait until there is a pause to join, the
aria-live=”polite” indicates a change when there is a break in the user experience. So, let’s start with fleshing out a div element:
<div aria-live=”polite”>

Then we need to decide how much context is required for the user to understand the update. If the entire live region must be presented for the change to make sense, assign the aria-atomic attribute with the value of true to the HTML element.

Repeating unchanged information may become redundant or make it harder to tell apart what portion has changed. If you want to communicate only the change and that change makes sense on its own, assign the aria-atomic attribute with the value of false to the HTML element:
<div aria-live=”polite” aria-atomic=”false”>

Finally, identify the type of update. Assign the relevant attribute to the HTML element. The types of update are:

relevant=”additions”, where new nodes are added to the DOM
relevant=”removals”, where nodes are removed from the DOM
relevant=”text”, where changes occur to the text within existing nodes

You may assign multiple values to the relevant attribute by adding a space between values:
<div aria-live=”polite” aria-atomic=”false” relevant=”additions removals text”>

In fact, the default behavior should be relevant=”additions text”. This reflects the most common type of changes.

Summary

ARIA live regions provide a standardized way to alert assistive technology that a DOM change has occurred and tell it how to handle the change.
You may also prevent updates from being announced until all of the changes in a live region finish updating by changing the live region’s state. You do this by dynamically setting the attribute state (aria-busy=”true”) and then clearing it when the updates are ready to be announced. This might be useful when multiple updates in a live region need to be announced together to make sense.

Here is the list of other related tutorials that are highly recommended: