aria-relevant
Indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. Controls which types of changes are announced.
Overview
The aria-relevant attribute fine-tunes which types of changes within a live region trigger announcements to screen readers.
By default, both additions and text changes are announced. You can customize this to only announce specific types of changes: additions, removals, text modifications, or any combination.
Why Use aria-relevant?
In a chat application, you might want to announce when messages are added but not when they're removed (cleanup). In a task list, you might announce both additions and removals but ignore text updates. This attribute lets you control exactly what gets announced.
Live Demo: aria-relevant Values
Current setting: aria-relevant="additions text"
Last action: None yet
Will announce additions. Will announce text changes.
Attribute Values
additionsAnnounce when nodes are added to the live region. Use for feeds, logs, chat applications where new content appears.
removalsAnnounce when nodes are removed from the live region. Useful for task lists, shopping carts where items are deleted.
textAnnounce when text content of existing nodes changes. Use for status messages, counters, or labels that update.
allAnnounce all changes - additions, removals, and text. Equivalent to "additions removals text".
additions text(default)Announce additions and text changes, but not removals. This is the default when aria-relevant is not specified.
Code Examples
aria-relevant="additions"
<!-- aria-relevant="additions" - Only announce additions -->
<ul role="log"
aria-live="polite"
aria-relevant="additions">
<li>Message 1</li>
<li>Message 2</li>
<!-- New messages will be announced -->
<!-- Removals and updates will NOT be announced -->
</ul>aria-relevant="removals"
<!-- aria-relevant="removals" - Only announce removals -->
<ul role="log"
aria-live="polite"
aria-relevant="removals">
<li>Task 1</li>
<li>Task 2</li>
<!-- When items are removed, screen reader announces -->
<!-- Additions and text changes will NOT be announced -->
</ul>aria-relevant="text"
<!-- aria-relevant="text" - Only announce text changes -->
<div role="status"
aria-live="polite"
aria-relevant="text">
<p id="status-text">Ready</p>
<!-- Changing text content will be announced -->
<!-- Adding/removing elements will NOT be announced -->
</div>
<script>
function updateStatus(newText) {
document.getElementById('status-text').textContent = newText;
// Screen reader announces: "Processing..."
}
updateStatus('Processing...');
</script>All Changes
<!-- aria-relevant="all" - Announce everything -->
<div role="log"
aria-live="polite"
aria-relevant="all">
<div class="notification">Status update</div>
<!-- Announces additions, removals, and text changes -->
<!-- Equivalent to "additions removals text" -->
</div>Multiple Values
<!-- Multiple values (space-separated) -->
<ul role="log"
aria-live="polite"
aria-relevant="additions text"
aria-atomic="false">
<li>Log entry 1</li>
<li>Log entry 2</li>
<!-- Announces when items are ADDED -->
<!-- Announces when text content CHANGES -->
<!-- Does NOT announce removals -->
</ul>
<script>
const log = document.querySelector('[role="log"]');
// This WILL be announced (addition)
const newItem = document.createElement('li');
newItem.textContent = 'New log entry';
log.appendChild(newItem);
// This WILL be announced (text change)
log.querySelector('li').textContent = 'Updated entry';
// This will NOT be announced (removal)
log.removeChild(log.lastChild);
</script>React Component
// React Component with aria-relevant
import { useState } from 'react';
function TaskList() {
const [tasks, setTasks] = useState([
{ id: 1, text: 'Buy groceries', completed: false },
{ id: 2, text: 'Walk the dog', completed: false },
]);
const addTask = (text) => {
setTasks([...tasks, {
id: Date.now(),
text,
completed: false
}]);
};
const removeTask = (id) => {
setTasks(tasks.filter(t => t.id !== id));
};
const toggleTask = (id) => {
setTasks(tasks.map(t =>
t.id === id ? { ...t, completed: !t.completed } : t
));
};
return (
<div>
{/* Live region for task updates */}
<ul
role="log"
aria-live="polite"
aria-relevant="additions removals"
aria-atomic="false"
>
{tasks.map(task => (
<li key={task.id}>
<input
type="checkbox"
checked={task.completed}
onChange={() => toggleTask(task.id)}
aria-label={task.text}
/>
<span className={task.completed ? 'completed' : ''}>
{task.text}
</span>
<button onClick={() => removeTask(task.id)}>
Remove
</button>
</li>
))}
</ul>
{/* Will announce: "Buy milk" when added */}
{/* Will announce: "Buy groceries" when removed */}
{/* Will NOT announce text changes (completion status) */}
<form onSubmit={(e) => {
e.preventDefault();
const input = e.currentTarget.elements.namedItem('task');
addTask(input.value);
input.value = '';
}}>
<input type="text" name="task" placeholder="New task" />
<button type="submit">Add Task</button>
</form>
</div>
);
}Best Practices
Use "additions" for feeds, chat logs where only new content matters
Use "additions removals" for task lists, shopping carts
Use "text" for status indicators that change but don't add/remove elements
Use "all" when every change is important to communicate
Consider user needs - announce what adds value, skip what doesn't
Test each configuration with real screen readers
Don't announce removals for decorative or temporary elements
Don't use "all" by default - it can be too verbose
Don't forget some changes might confuse users if announced
Don't announce purely visual changes that lack meaning
Common Use Cases
additions
- • Chat messages (new only)
- • News feeds (new articles)
- • Notification lists
- • Activity logs
- • Social media timelines
additions removals
- • Shopping cart items
- • To-do lists
- • Selected file lists
- • Tag collections
- • Playlist management
text
- • Status indicators
- • Progress percentages
- • Timer displays
- • Score counters
- • Form validation messages
all
- • Complex data grids
- • Collaborative editing
- • Real-time dashboards
- • Multi-user interfaces
- • Live collaboration tools
Accessibility Notes
Default Behavior
If you don't specify aria-relevant, the default is "additions text". This covers most common scenarios where you want to announce new content and text updates.
Multiple Values
You can combine multiple tokens in a space-separated list: "additions removals". This gives you fine-grained control over exactly which changes trigger announcements.
Performance Impact
The more change types you monitor, the more processing the browser does. Using"all" monitors everything, which can impact performance in rapidly updating regions. Be specific when possible.