Loading Developer Playground

Loading ...

Skip to main content
ARIA ATTRIBUTELive Region Attributes

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.

Attribute Type
Live Region
Value Type
Token list
Default Value
additions text

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

Item 1
Item 2
Item 3

Current setting: aria-relevant="additions text"

Last action: None yet

Will announce additions. Will announce text changes.

Attribute Values

additions

Announce when nodes are added to the live region. Use for feeds, logs, chat applications where new content appears.

removals

Announce when nodes are removed from the live region. Useful for task lists, shopping carts where items are deleted.

text

Announce when text content of existing nodes changes. Use for status messages, counters, or labels that update.

all

Announce 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.

Related Attributes

Specifications & Resources