Why authors should avoid aria-relevant
By Aaron Leventhal and Rob Dodson
Short version
The ARIA attribute, aria-relevant, is supposed to affect how live regions are processed by screen readers. It is designed to provide a hint to screen readers that content being removed from a web page should be announced to the user (similar to how a deleted character is announced in a text field).
However, aria-relevant rarely works as intended and does not have a real-world use case. Therefore, aria-relevant should never be used. If you’re creating an ARIA live region, we recommend you ignore aria-relevant and just rely on the default live region behavior, which is to speak all new content. As this article will explain, this is ultimately the most desirable and effective behavior.
Backstory: why is aria-relevant in the ARIA spec?
The W3C originally added aria-relevant to ARIA because theoretically a screen reader should be informed about any live region changes and be able to receive hints on whether those changes are useful. It seemed bad to develop a standard where it wasn’t possible to have removals of content be presented. After all, it should be up to the screen reader — not the browser — to decide what’s important. However, aria-relevant is not actually necessary for this. Even without aria-relevant, screen readers are still informed about all changes in the document. All the aria-relevant attribute really does is suggest to a screen reader which changes might be interesting.
It’s significant that in all the years ARIA has existed, aria-relevant has never really found a true purpose. Right now, it’s pretty certain that if an author uses aria-relevant it is because they were confused by its purpose and maybe thought it was a helpful band-aid for fixing a bug, and it probably wasn’t.
Different values for aria-relevant and their lack of importance
Speaking new content: “additions” vs “text” vs “additions text” (the default)
Let’s look at a simple example:
<div aria-live=”polite”></div>By default this live region has an implicit value of:
aria-relevant=”additions text”This means that the following will be spoken:
- “additions”: nodes with text equivalents added to the live region, such as <img alt>
- “text” : any new text added to the live region
But it’s unclear why or whether inserting a text node should be any different from just changing text, or inserting an element with a text equivalent. No one has ever suggested a case where you want one but not the other — this does not exist usefully in the wild. In retrospect, the value “text” should never have been created by the standards committee.
What to do instead: if you just want the normal behavior of speaking added content, leave out the aria-relevant attribute.
Speaking removed content: “additions text removals” or “all” (equivalent)
The aria-relevant attribute was really added so that removals could be spoken, via
aria-relevant=”additions text removals” or the shorthand
aria-relevant=”all”Let’s update our example from above to match:
<div id=”current-users” aria-live=”polite” aria-relevant=”all”></div>The only use case that has been suggested for a snippet like the above is a chat pane that lists current users. If a user drops offline and is removed from the list, a screen reader is informed about the removal. Typically, screen readers don’t announce removal of content from a web page, however, if the author adds aria-relevant=”all”, those removals would be announced — at least in theory. But today it seems that VoiceOver and NVDA won’t announce anything at all. JAWS will announce the removal (speaking the text, followed by “removed”), but only if you remove a descendant of the region, and not the region itself.
What to do instead: even if screen readers worked properly, a better experience is to add a line to the chat for the event that occurred, create a status line, or even use an invisible live region, inserting the text, “Harry has left the chat”.
Wrapping up
There is currently a bug to find real-world use cases, and consider deprecating aria-relevant. For the foreseeable future, we recommend authors avoid using this attribute, and instead opt for one of the alternatives mentioned above.
