JavaScript Element ariaRelevant Property

What You’ll Learn

Element.ariaRelevant is an instance property that reflects the aria-relevant attribute. Learn which live-region changes get announced (additions, removals, text, all), how it pairs with aria-live, and how to get or set the property from JavaScript—with five examples and try-it labs.

Introduction

A live region tells assistive technologies that content may update. Not every update is equally useful—sometimes you care about new nodes, sometimes only text changes, sometimes removals too.

aria-relevant filters which kinds of changes should be announced. ariaRelevant is the JavaScript reflection of that attribute.

const el = document.getElementById("clock");
console.log(el.ariaRelevant); // "all"
el.ariaRelevant = "text";

Understanding the Property

MDN: the ariaRelevant property of the Element interface reflects the value of the aria-relevant attribute, which indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. It describes which changes in an aria-live region are relevant and should be announced.

• Reflected attribute — mirrors aria-relevant.
• Get / set — readable and writable string (space-separated tokens).
• Live-region filter — works with aria-live regions.
• Non-standard IDL — MDN marks the property Non-standard (Baseline widely available).

📝 Syntax

ariaRelevant

Value

A string containing one or more of the following values, space separated:

📋 MDN Example Shape

MDN starts with a timer live region marked aria-relevant="all", then narrows it to "text":

<div
  id="clock"
  role="timer"
  aria-live="polite"
  aria-atomic="true"
  aria-relevant="all"
></div>

let el = document.getElementById("clock");
console.log(el.ariaRelevant); // all
el.ariaRelevant = "text";
console.log(el.ariaRelevant); // text

Pair with ariaLive and often ariaAtomic so urgency and announcement scope match your UI updates.

Examples Gallery

Examples follow MDN Element: ariaRelevant. Labs use a live region so you can safely read and write the property.

const el = document.getElementById("clock");
console.log(el.ariaRelevant);

// HTML includes: aria-live="polite" aria-relevant="all"

all

let el = document.getElementById("clock");
console.log(el.ariaRelevant); // all
el.ariaRelevant = "text";
console.log(el.ariaRelevant); // text

all
text

const region = document.createElement("div");
region.setAttribute("role", "status");
region.setAttribute("aria-live", "polite");
region.setAttribute("aria-label", "Updates");
document.body.appendChild(region);

region.ariaRelevant = "additions text";
console.log({
  ariaRelevant: region.ariaRelevant,
  attr: region.getAttribute("aria-relevant")
});

{
  "ariaRelevant": "additions text",
  "attr": "additions text"
}

const el = document.createElement("div");
el.setAttribute("role", "timer");
el.setAttribute("aria-live", "polite");
el.setAttribute("aria-relevant", "all");
document.body.appendChild(el);

el.ariaRelevant = "text";
console.log({
  fromProperty: el.ariaRelevant,
  fromAttribute: el.getAttribute("aria-relevant"),
  same: el.ariaRelevant === el.getAttribute("aria-relevant")
});

{
  "fromProperty": "text",
  "fromAttribute": "text",
  "same": true
}

console.log({
  supported: "ariaRelevant" in Element.prototype,
  allowed: ["additions", "removals", "text", "all"],
  pairWith: "ariaLive / aria-live",
  tip: "MDN: Non-standard IDL — test with a screen reader",
  status: "Non-standard · Baseline Widely available (MDN)"
});

{
  "supported": true,
  "allowed": ["additions", "removals", "text", "all"],
  "pairWith": "ariaLive / aria-live",
  "tip": "MDN: Non-standard IDL — test with a screen reader",
  "status": "Non-standard · Baseline Widely available (MDN)"
}

🚀 Common Use Cases

• Clocks or timers that update text and should announce text changes only.
• Feeds that announce new items (additions) but stay quiet on removals.
• Status panels that announce every change type with all.
• Chat or log UIs that care about new nodes and text updates together.
• Keeping script and markup aligned without manual setAttribute.

🔧 How It Works

📝 Notes

• MDN: Non-standard IDL property (also Baseline Widely available since Oct 2023).
• Not labeled Deprecated or Experimental on the MDN page.
• Needs a live region (aria-live or equivalent) to be meaningful.
• Related: ariaReadOnly, ariaLive, ariaRequired, JavaScript hub.

💡 Best Practices