aria-atomic

When to use

On a live region whose updates only make sense when read as a complete unit. The classic example is a single-line status like “3 results found” — if the live region is aria-atomic="false" (the default) and only the number changes, the screen reader may announce just “3”, stripped of context. With aria-atomic="true", it announces the entire sentence.

Set aria-atomic="false" (or omit it) when:

• The region is a log or chat panel where each new line is self-contained — “Alice: hello”, “Bob: hi”. Announcing the whole log every time would be unbearable.
• Only the new content carries the new information.

Set aria-atomic="true" when:

• The region is a short, stable phrase whose meaning depends on neighbouring words — “Cart total: $42.18”, “Page 3 of 12”, “Filters applied: 2”.
• A small DOM change inside the region carries little meaning on its own.

aria-atomic is independent of aria-live and aria-busy. They work together but tune different aspects.

How to keep it in sync

Valid values are "true" and "false". The default is "false".

Set the attribute once on the live region and leave it alone — it is a property of how the region should be announced, not a state that changes over time. It is also inherited: applying aria-atomic="true" to a parent makes descendant live regions atomic unless overridden.

If your update strategy is “replace the whole region’s text”, aria-atomic="true" produces the most natural announcement. If your update strategy is “append a new line”, you usually want aria-atomic="false" so only the appended line is read.

Common failures

• Leaving aria-atomic at its default on a stable single-line status, then hearing only “5” announced instead of “5 results found”.
• Setting aria-atomic="true" on a chat log — every new message causes the entire log to be re-read.
• Updating only a <span> inside an atomic region and being surprised that the surrounding text is announced too. That is exactly what atomic means.
• Using aria-atomic on a region that has no aria-live and no implicit live role — it has no effect.
• Setting aria-atomic on a focusable control. Live region attributes belong on status containers, not interactive elements.

Example

<!-- Atomic: the whole sentence is the message -->
<p aria-live="polite" aria-atomic="true">
  Cart total: <span id="cart-total">$0.00</span>
</p>

<!-- Non-atomic: only the new line is announced -->
<ul aria-live="polite" aria-atomic="false" id="chat-log">
  <li>Alice: hi there</li>
</ul>