aria-atomic
Indicates whether assistive technologies will present all, or only parts of, the changed region when updates occur. Controls how screen readers announce live region updates.
Overview
The aria-atomic attribute determines whether screen readers will announce only the changed content or the entire live region when an update occurs.
When set to true, the entire region is announced. When set to false (default), only the changed nodes are announced.
When to Use aria-atomic="true"
Use aria-atomic="true" when the changed content needs surrounding context to make sense. For example, updating a number without its label ("5") is confusing, but the full region ("5 unread messages") provides clarity.
Live Demo: aria-atomic Comparison
What screen readers announce when aria-atomic="true":
- • Message update: "5 unread messages" (full context)
- • Score update: "Player: Player1 | Score: 0" (full context)
Attribute Values
trueWhen set to true, assistive technologies will present the entire region as a single unit when any part changes. This provides full context but can be verbose.
false(default)When set to false or omitted, assistive technologies will present only the changed nodes within the region. More concise but may lack context.
Code Examples
aria-atomic="true"
<!-- aria-atomic="true" - Announces entire region -->
<div role="status"
aria-live="polite"
aria-atomic="true">
<span id="count">5</span> unread messages
</div>
<!-- When count changes from 5 to 6:
Screen reader announces: "6 unread messages" (entire region) -->aria-atomic="false"
<!-- aria-atomic="false" - Announces only changed content -->
<div role="status"
aria-live="polite"
aria-atomic="false">
<span id="count">5</span> unread messages
</div>
<!-- When count changes from 5 to 6:
Screen reader announces: "6" (only the changed part) -->Scoreboard (Needs Context)
<!-- Game Scoreboard Example -->
<div role="status"
aria-live="polite"
aria-atomic="true"
class="scoreboard">
<span class="player">Player: <strong id="player-name">Alice</strong></span>
<span class="score">Score: <strong id="score-value">100</strong></span>
</div>
<!-- When score changes:
aria-atomic="true": "Player: Alice, Score: 150" (full context)
aria-atomic="false": "150" (just the number, confusing!) -->
<script>
function updateScore(newScore) {
document.getElementById('score-value').textContent = newScore;
// Screen reader will announce entire scoreboard with context
}
</script>React Component
// React Component with aria-atomic
import { useState } from 'react';
function LiveRegionExample() {
const [items, setItems] = useState(3);
const [atomic, setAtomic] = useState(true);
const addItem = () => {
setItems(prev => prev + 1);
};
return (
<div>
<div
role="status"
aria-live="polite"
aria-atomic={atomic}
className="live-region"
>
You have <strong>{items}</strong> items in your cart
</div>
<button onClick={addItem}>
Add Item
</button>
<label>
<input
type="checkbox"
checked={atomic}
onChange={(e) => setAtomic(e.target.checked)}
/>
Use aria-atomic="true"
</label>
<div className="explanation">
<strong>Current behavior:</strong>
{atomic ? (
<p>Will announce: "You have {items} items in your cart"</p>
) : (
<p>Will announce: "{items}" (number only)</p>
)}
</div>
</div>
);
}Common Use Cases
true
- ✓Status messages: "5 items added"
- ✓Counters with labels: "3 unread emails"
- ✓Compound info: "Player: Alice, Score: 150"
- ✓Notifications: Icons + text together
- ✓Progress indicators: "Step 2 of 5"
false
- ✓Log entries: New lines in chat/console
- ✓Self-contained text: Complete messages
- ✓List additions: New items in a feed
- ✓Standalone numbers: When label doesn't change
- ✓Timer updates: Just the time value
Best Practices
Use aria-atomic="true" when changed content needs context to be understood
Use aria-atomic="true" for status messages with labels (e.g., "5 items in cart")
Use aria-atomic="true" for compound updates (multiple pieces of info)
Use aria-atomic="false" when the changed content is self-explanatory
Always pair with aria-live to create effective live regions
Test with screen readers to ensure announcements make sense
Don't use aria-atomic="true" for very long regions (too verbose)
Don't use aria-atomic="false" when context is essential
Don't assume the default (false) is always appropriate
Don't forget to consider verbosity vs clarity trade-off
Accessibility Notes
Screen Reader Announcements
With aria-atomic="true", screen readers announce the entire live region's text content when any part changes. This ensures users hear the full context. With false, only the specific changed node is announced, which is more concise but can be confusing without context.
Timing Considerations
Using aria-atomic="true" can make announcements longer. If your live region updates frequently, consider whether users will be overwhelmed by verbose announcements. Balance context with brevity based on update frequency.
Browser Support
aria-atomic is well-supported across modern browsers and screen readers. However, the exact behavior can vary slightly. Always test with NVDA, JAWS, and VoiceOver to ensure consistent user experience.