aria-relevant — Controlling Which Live Region Changes Are Announced

In this tutorial, you will learn about aria. We cover key concepts, practical examples, and best practices to help you master this topic.

aria-relevant controls which types of content changes in a live region trigger announcements, with values additions, removals, text, and all determining what screen readers announce.

In this tutorial, you'll learn how to fine-tune live region announcements with aria-relevant in your ARIA implementations.

What You'll Learn

By the end of this lesson, you'll understand the four aria-relevant token values, how to combine them, the default behavior, and when to customize the relevant changes.

Why It Matters

By default, screen readers only announce additions to live regions. If your widget also needs to announce removals or text changes, aria-relevant is essential.

Real-World Use

Doda Browser's download manager uses aria-relevant="additions removals" on the download list so users hear when files start and finish downloading.

Change Types

flowchart TD
  A[Content Change Types] --> B[additions]
  A --> C[removals]
  A --> D[text]
  A --> E[all]
  B --> F[Elements added to DOM]
  C --> G[Elements removed from DOM]
  D --> H[Text content modified]
  E --> I[Everything = additions removals text]

How aria-relevant Works

aria-relevant accepts a space-separated list of tokens:

<div aria-live="polite" aria-relevant="additions removals" id="notification-list">
  <!-- announced when items are added or removed -->
</div>

Token Values

Default Behavior

The default value is "additions text". Screen readers announce new elements and text changes but not removals:

<!-- Default behavior: announces additions and text changes -->
<div aria-live="polite" id="log">
  <!-- Content changes here -->
</div>

<!-- Equivalent explicit declaration -->
<div aria-live="polite" aria-relevant="additions text" id="log">
  <!-- Content changes here -->
</div>

Customizing Announcements

<!-- Chat application: new messages added -->
<div role="log" aria-live="polite" aria-relevant="additions">
  <!-- new messages appear as children -->
</div>

<!-- File manager: announce when files appear or disappear -->
<div aria-live="polite" aria-relevant="additions removals" id="file-list">
  <!-- file items added/removed here -->
</div>

Common Mistakes

• Using aria-relevant="all" everywhere: Removals announcements can be noisy and disorienting.
• Not setting aria-relevant on role="log": The log role defaults to "additions" only.
• Setting aria-relevant without aria-live: It has no effect outside a live region.
• Expecting removals to work across all screen readers: Support for removals is less consistent.
• Over-announcing with too many change types: Keep announcements focused on what the user needs.

Practice and Challenge

1. What is the default value of aria-relevant? "additions text".

2. Which token announces elements being removed? removals.

3. How do you announce all change types? aria-relevant="all".

4. When should you add "removals" to aria-relevant? When users need to know that items were removed, such as in a file manager or shopping cart.

5. Challenge: Create a todo list that uses aria-relevant="additions removals" to announce items being added and removed.

FAQ

Mini Project

Build a notification system that announces notifications as they arrive and also announces when a user dismisses a notification. Use aria-relevant="additions removals".

What's Next

Continue to aria-busy to learn how to indicate loading or updating elements.