WAI-ARIA: aria-atomic (Property)

Description

Indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the aria-relevant attribute.

Both accessibility APIs and the Document Object Model [dom] provide events to allow the assistive technologies to determine changed areas of the document.

When the content of a live region changes, user agents SHOULD examine the changed element and traverse the ancestors to find the first element with aria-atomic set, and apply the appropriate behavior for the cases below.

1. If none of the ancestors have explicitly set aria-atomic, the default is that aria-atomic is false, and assistive technologies will only present the changed node to the user.
2. If aria-atomic is explicitly set to false, assistive technologies will stop searching up the ancestor chain and present only the changed node to the user.
3. If aria-atomic is explicitly set to true, assistive technologies will present the entire contents of the element, including the author-defined live region label if one exists.

When aria-atomic is true, assistive technologies MAY choose to combine several changes and present the entire changed region at once.

Browser Compatibility

Screen Reader support

aria-atomic Example

HTML Example

<div aria-live="polite" aria-atomic="true">
  <h3>the current score is</h3><span>23/0 after 5 Overs</span>
</div>

Characteristics

Used in roles

• All elements of the base markup

Value

• True/False
  Value representing either true or false. The default value for this value type is False, unless otherwise specified.
• False (default)
• Assistive technologies will present only the changed node or nodes.
• True:
  • Assistive technologies will present the entire changed region as a whole, including the author-defined label if one exists.

Semantic HTML

No HTML element equivalent.

Reference

• WAI-ARIA 1.2 Specification
  Refer to the notes from the WAI-ARIA 1.2 specification for more information on aria-atomic.
• A11Y Support
  The screenreader compatibility for each of the ARIA attributes is taken from the A11Y Support. Please refer to the original source if screenreader compatibility is updated for aria-atomic.
• 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-atomic.