WAI-ARIA: aria-relevant (Property)
Description
Indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. See related aria-atomic.
The attribute is represented as a space delimited list of the following values: additions, removals, text; or a single catch-all value all.
This is used to describe semantically meaningful changes, as opposed to merely presentational ones. For example, nodes that are removed from the top of a log are merely removed for purposes of creating room for other entries, and the removal of them does not have meaning. However, in the case of a buddy list, removal of a buddy name indicates that they are no longer online, and this is a meaningful event. In that case aria-relevant will be set to all. When the aria-relevant attribute is not provided, the default value, additions text, indicates that text modifications and node additions are relevant, but that node removals are irrelevant.
Note: aria-relevant values of removals or all are to be used sparingly. Assistive technologies only need to be informed of content removal when its removal represents an important change, such as a buddy leaving a chat room.
Note: Text removals should only be considered relevant if one of the specified values is ‘removals’ or ‘all’. For example, for a text change from ‘foo’ to ‘bar’ in a live region with a default aria-relevant value, the text addition (‘bar’) would be spoken, but the text removal (‘foo’) would not.
aria-relevant is an optional attribute of live regions. This is a suggestion to assistive technologies, but assistive technologies are not required to present changes of all the relevant types.
When aria-relevant is not defined, an element’s value is inherited from the nearest ancestor with a defined value. Although the value is a token list, inherited values are not additive; the value provided on a descendant element completely overrides any inherited value from an ancestor element.
When text changes are denoted as relevant, user agents MUST monitor any descendant node change that affects the text alternative computation of the live region as if the accessible name were determined from contents (nameFrom: contents). For example, a text change would be triggered if the HTML alt attribute of a contained image changed. However, no change would be triggered if there was a text change to a node outside the live region, even if that node was referenced (via aria-labelledby) by an element contained in the live region.
Browser Compatibility
| desktop | mobile | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
ariaRelevant | ChromeFull support81 | EdgeFull support81 | FirefoxNo supportNo | Internet ExplorerNo supportNo | OperaFull support68 | SafariFull support12.1 | WebView AndroidFull support81 | Chrome AndroidFull support81 | Firefox for AndroidNo supportNo | Opera AndroidFull support58 | Safari on iOSFull support12.2 | Samsung InternetFull support13.0 |
aria-relevant Example
HTML Example
<div class="errors" role="alert" aria-relevant="all"> <ul>
</ul>
</div>Characteristics
Used in Roles
- All elements of the base markup
Value
- token
listA list of one or more tokens. - Additions
- Element nodes are added to the accessibility tree within the live region.
- additions text
- Equivalent to the combination of values, “additions text”.
- all
- Equivalent to the combination of all values, “additions removals text”.
- removals
- Text content, a text alternative, or an element node within the live region is removed from the accessibility tree.
- text
- Text content or a text alternative is added to any descendant in the accessibi
Semantic HTML
No HTML element equivalent.
Why authors should avoid aria-relevant?
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.
More at medium
Reference
- WAI-ARIA 1.2 Specification
Refer to the notes from the WAI-ARIA 1.2 specification for more information on aria-relevant. - MDN Web Docs
The browser compatibility for each of the ARIA attributes is taken from the MDN Web Docs. Please refer to the original source if browser compatibility is updated for aria-relevant. - Why authors should avoid aria-relevant – Medium
