Main content

aria-atomic

Characteristics

Type:

  • DOMString

Used in Roles:

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

See related:

  • aria-relevant

Value:

  • A value that specifies how to present change notifications.
  • true/false
    • true: Present the entire region as a whole when changes are detected.
    • false (default): Present only the changed regions.

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.

The aria-atomic property is used along with aria-live property when the page contains live regions.

On a web page when auto-updating content such as live chat widget is available, the content frequently gets updated. In this scenario, users need to know only the updated content that means the recently received message but not the entire chat content. In certain scenarios, it does not make sense if only the updated sentence or line is captured by assistive technologies. aria-atomic is used when entire live region should be intimated to the user.

Example 

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

In the above content, only the sentence in the span tag will update frequently but it does not make sense on its own. So aria-atomic is used to capture the statement before the span as well. ARIA-atomic should be set to true for the assistive technologies to get the information of the entire live region. aria-relevant property will be used if only a portion of the live region needs to be intimated to the assistive technologies.

Both accessibility APIs and the Document Object Model 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.

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

Syntax

<element aria-atomic="true|false" ... /> 

Microsoft Active Accessibility Properties:

  • N/A

UI Automation Properties: 

  • N/A

UI Automation AriaProperties Property:

  • atomic