• Skip to primary navigation
  • Skip to main content
  • Skip to primary sidebar
Logo for DigitalA11Y

Digital A11Y

Your Accessibility Partner

  • About
    • Bio
      • Conference Speaking
      • Videos
      • mentions
  • Articles
  • Resources
    • WAI-ARIA
    • WCAG
    • Cheat Sheets
    • A11Y Blogs
    • A11Y Toolkit
  • Contact
You are here: Home / WAI-ARIA: aria-relevant (Property)

WAI-ARIA: aria-relevant (Property)

Indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified.

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.

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 list
    • A 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 https://medium.com/dev-channel/why-authors-should-avoid-aria-relevant-5d3164fab1e3

Reference

W3C (opens new window)
Medium (opens new window)

Share A11Y Love

  • Twitter
  • LinkedIn
  • Facebook
  • Reddit

Primary Sidebar

Get Digital A11Y in Your Inbox

Recent A11Y Articles

  • WCAG 2.1 Checklist
  • A Sneak peek into WCAG 3.0 First Public Draft
  • Understanding SC 4.1.3 Status messages
  • Understanding SC 2.5.4 Motion Actuation
  • Understanding SC 2.5.3 Label in Name

Recent Comments

  • Isaac Williams on Digital Accessibility Companies Roundup
  • Vaibhav Mishra on Understanding SC 3.3.1 Error Identification
  • Vaibhav Mishra on Understanding SC 1.3.2 Meaningful Sequence
  • Donal Rice on Digital Accessibility Companies Roundup
  • Rajath on A Sneak peek into WCAG 3.0 First Public Draft

A11Y Categories

  • Design
  • Events
  • HTML
  • IOS
  • Mobile Accessibility
  • News
  • Tools
  • WAI-ARIA
  • WCAG
  • Web Accessibility

  • Privacy Policy
  • Sitemap
© 2021 Digital A11Y