Live Regions
- Kim Collins (Unlicensed)
Live regions are used to ensure that dynamic changes to page content are announced to users who might not be able to visually see the content change.
Certain ARIA roles (alert, log, or status) or the aria-live attribute are used to create live regions. This will programmatically identify parts of a page where content may change dynamically.
While any HTML element can be used to contain a live region; typically, they are contained in a <div>. When the content in an live region container changes, the content is automatically read by the screen reader, without the screen reader having to focus on the place where the text is displayed.
When to use a Live Region
Any time content is updated dynamically after a page has initially loaded, a live region should be used.
Examples of where live regions are useful:
- a success message indicating a user's action was successfully completed (e.g. "Your message was sent.")
- a status message indicating that search results have been updated (e.g. "10 results found")
- a warning that a user's form submission has errors
Roles and Attributes
Live regions are created by using the ARIA roles alert, log, or status or, alternatively, the aria-live attribute. There are three possible values for the aria-live attribute, each of which correspond to the ARIA roles alert, log, or status. Each setting determines how and when the content in the live region is announced.
Warning
Screen readers maintain a message queue for live regions. “alert” or "assertive" items take priority over “status” or "polite" items. Some screen readers will clear the queue after announcing an alert or assertive item.
role=“status” / aria-live="polite”
Status live regions announce updates "at the next graceful opportunity, such as at the end of speaking the current sentence or when the user pauses typing", according to the WAI-ARIA specification.
These live regions are appropriate for notifications that are important but do not require the user's immediate attention.
Examples include:
A newspaper website updating headlines.
role=”alert” / aria-live="assertive”
Alert live regions announce updates immediately.
These live regions are appropriate where the user needs to be warned of or informed of something before they move forward in their interaction with the page. The user’s screen reader will be interrupted for this message.
Examples include:
Asking a user if they are sure they want to proceed with deleting an item
Informing a user that their form submission has errors
Note: alert/assertive live regions should be used with caution, and only when the update requires the user’s immediate attention, for two reasons:
The announcement will interrupt the user in their current task, and
Other queued announcements may be cleared when an assertive item is announced.
aria-live="off”
Live regions with aria-live="off" should only announce updates if keyboard focus is currently on the element being updated.
For aria-live, “off” is the default setting.
Warning
If aria-live="off" is part of your messaging strategy, use only the aria-live attribute (with "polite", "assertive", or "off" as values) on the live region. Do not combine the aria-live attribute with a role that is implicitly aria-live (e.g. alert, status). The role may override the aria-live=”off” value.
Off is appropriate when the content updates would be "noise" for a user who is currently focused on other content. It is often used when making changes to the live region (e.g. to avoid announcements of old content while the new content is being provided).
Examples include:
Time changing on a countdown clock - a user does not need to know about these changes, unless they are currently focused on the countdown clock.
Updates to a stock ticker
Additional ARIA Properties
aria-atomic
Live regions with the aria-atomic attribute set to true will announce the contents of the entire region, even when only part of the content has changed. (i.e. All descendant nodes are always presented together).
If aria-atomic is set to false, only the updated content may be announced, depending on the user agent and assistive technology.
Setting aria-atomic="true" on a live region is useful if the content being updated does not make sense on its own, but needs the surrounding content for the user to understand the announcement.
An example might be an update to the current temperature in a weather widget:
<div role="status" aria-live="polite" aria-atomic="true">
<h3>Current temperature:</h3>
<p>26°C</p>
</div>
In the above example, both the "Current temperature" heading and the temperature value would be announced. If aria-atomic was set to false, only the temperature value might be announced, leaving the user confused about why the announcement was made or what the information meant.
aria-busy
If the content in a live region may take time to fully update (e.g. if a JavaScript function takes time to execute, or if the region is updated in multiple parts), the aria-busy attribute can used.
Set aria-busy to false by default, then set it to true while content is being updated, and set to false again once the content has been fully updated.
Note that aria-busy is not supported by all browsers and assistive technology, but can provide a benefit for users of technologies that do support it.
aria-relevant
Do not use the aria-relevant attribute. The attribute is not well supported by assistive technology. Generally, there is no need to change the default settings of aria-relevant.
Live regions with the (optional) aria-relevant attribute can indicate what types of changes should be announced to the user. Any change that does not match the value of aria-relevant should not be announced. The default value for aria-relevant is “additions text”, which should announce to the user any addition to the element.
The available values are:
additions: Any node being added to the live region is considered relevant and announced.
text: Any new content being added to existing nodes is considered relevant and announced.
removals: The deletion of any nodes is considered relevant and announced.
all: All changes are announced. This is equivalent to “additions removals text”.
Roles that are implicitly aria-live
Certain roles are implicitly aria-live regions; the role determines the default value of the aria-live attribute.
User agent and assistive technology support for roles that are implicitly aria-live is still not 100% (as of early 2019). With the exception of aria-live="off", the above roles should be used in combination with the corresponding aria-live attribute (e.g. <div role="alert" aria-live="assertive">). Once support improves, the aria-live attribute can be removed from elements with live region roles.
| role | aria-live | aria-atomic | description |
|---|---|---|---|
| status | polite | true | Updated information about the user's or application's status. A user is notified via the screen reader when messages are added. Updates to the region will result in the screen reader presenting its entire contents to the user. |
| alert | assertive | true | Important, possibly time-sensitive, information. Errors or warning messages, client side validation notices, etc. A user is notified via the screen reader immediately when messages are added. Updates to the region will result in the screen reader presenting its entire contents to the user. |
| log | polite | false | Informs user when content has been appended to sequential information (e.g. chat, error, history, etc.). A user is notified via the screen reader when messages are added. |
| marquee | off | false | Presents non-essential information that changes frequently (e.g. stock ticker). The difference between a marquee and a log is that logs usually have a meaningful order or sequence of important content changes. |
| timer | off | false | Presents a numerical counter indicating an amount of elapsed time remaining or since a start point. |
Unfortunately, using roles in combination with their corresponding aria-live attributes may have a negative effect on browser/screen reader combinations that fully support live region roles. This page will be updated when support is more consistent.
How to use a Live Region
Warning
Only changes to a live region are announced. The region must be present (ideally on page load) before an update to the region can be announced.
Ensure the live region is already on the page when the page loads.
Content in a live region will not be announced on page load. You cannot insert a live region and make an announcement at the same time. The region needs to be on the page, and the accessibility API needs to be aware that it is there before any announcement can be sent to the screen reader.
Announcements are made when the live region is dynamically updated.
The screen reader will watch the live region for any changes. Updating the content in a live region is the preferred method of triggering an announcement.
(Some browser/screen reader combinations consider a change from display: none to display: block to be enough to trigger an announcement. Do not rely on this technique as not all browser/screen reader combinations support it.)
Keep announcements brief
Live region announcements are not navigable text. Screen readers allow users to interrupt these announcements. If a live region announcement is interrupted, it cannot be retrieved and the announcement will be lost. Short announcements are less likely to be interrupted.
Temporary Announcements
Live region announcements are frequently used to announce things that are temporary or time-sensitive, so it makes sense for the content of the announcement itself to be temporary. It should be removed from the page when the content is no longer correct or relevant.
Do not run the risk of having a screen reader user come across the leftover stale text of a live region announcement that is no longer relevant. The user may think that the web page is making the announcement again, when in reality they just happened to find the original announcement.
Turn it off
After updating a live region with temporary content, wait for some reasonable time so it can be announced, then turn the region off (using aria-live="off") and delete the text. Turn it on again by changing the aria-live value to “polite” or “assertive” before inserting new text.
Consider also hiding live regions (using CSS - do not remove it from the DOM) when they are not in use.
Resources
Using ARIA role=alert or Live Regions to Identify Errors
ARIA Live Regions
Related WCAG Criteria
WCAG 3.3.1 Error Identification (as a recommended technique)