Main content

aria-relevant

Characteristics

Type:

  • String

Used in Roles:

  • All elements of the base markup (Global)
  • No role required

See Related:

  • aria-atomic

Value:

  • token list
    • additions: Insertion of nodes into the live region should be considered relevant.
    • removals: Deletion of nodes should be considered relevant.
    • text: Changes to the textual content of existing nodes should be considered relevant.
    • all: Equivalent to the combination of all values, "additions removals text"
    • additions text (default): Equivalent to the combination of values, "additions text".

Sets or retrieves which changes to a live region are relevant.

The aria-relevant setting gives a hint about what types of changes are relevant and should be announced by assistive technology. Any change that is not relevant should be treated as if the region had aria-live="off" and should not be announced.

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.

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.

Both accessibility APIs and Document Object Model Level 2 Events provide events to allow assistive technologies to determine changed areas of the document.

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.

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.

Note  For cross-browser compatibility, always use the aria attribute syntax to access and modify ARIA properties, for example object.setAttribute("aria-valuenow", newValue).

Syntax

HTML
<element aria-relevant="p" ... >
JavaScript
object.setAttribute("aria-relevant",value);var value = object.getAttribute("aria-relevant");

Microsoft Active Accessibility Properties:

  • N/A

UI Automation Properties: 

  • N/A

UI Automation AriaProperties Property:

  • relevant
More in this category: « aria-readonly aria-required »