The HTML aria-atomic attribute
The aria-atomic attribute sets how much of a live region gets announced after an update. With aria-atomic="true", the whole region is read, such as a full score or time. Otherwise only the changed part is read, though WAI-ARIA makes true the default for status and alert.
Overview
The aria-atomic attribute tells assistive technology whether to announce all of a live region or only its changed parts. It goes on a region marked with aria-live or a live role such as status, or on an element inside one.
With the default, false, only the changed node is announced. In a clock that keeps hours and minutes in separate spans, a screen reader may say only 34 when 17:33 turns into 17:34. With aria-atomic="true", it reads the whole region and the listener hears 17:34.
Browsers should start at the changed element and walk up to the first ancestor that sets aria-atomic. An explicit false on an inner element therefore stops the search before a true higher up. A region set to true is read with the name you gave it, such as an aria-label, if it has one.
WAI-ARIA gives role="status" and role="alert" an implicit aria-atomic of true. Firefox marks them atomic only when aria-atomic="true" is written, though Chrome's accessibility tree marks both roles atomic without it. A role="log" region keeps false, so only its new entries are announced.
Syntax
<p id="score" aria-live="polite" aria-atomic="true">Home 2, Away 1</p>Values
| Value |
|---|
| true | false |
Example
<p id="score" aria-live="polite" aria-atomic="true">Home <span id="home">0</span>, Away <span id="away">0</span></p>
<button id="h">Home scores</button>
<button id="a">Away scores</button>
<p>With a screen reader running, each goal should be announced as the whole score, such as Home 1, Away 0.</p>
<script>
function goal(id) {
const el = document.getElementById(id);
el.textContent = Number(el.textContent) + 1;
}
document.getElementById('h').addEventListener('click', function () { goal('home'); });
document.getElementById('a').addEventListener('click', function () { goal('away'); });
</script>Best practices
- Set
aria-atomic="true"when the changed piece means nothing alone. Clock minutes and one team's half of a score are typical cases. - Keep atomic regions short. Every update inside them repeats the region's full text, its name included.
- Leave chat logs and activity feeds at the default
false, so each new message is announced without the history before it. - Inside an atomic panel, put
aria-atomic="false"on an inner block, so one changed line there doesn't make the screen reader re-read the whole panel. - Test the region with the screen readers your users have. The same live region can behave differently from one browser and assistive technology pairing to another.
