JavaScript Element ariaAtomic Property

What You’ll Learn

Element.ariaAtomic is an instance property that reflects the aria-atomic attribute on live regions. Learn the "true" / "false" string values, how it pairs with aria-live and aria-relevant, and how to get or set it from JavaScript—with five examples and try-it labs.

Introduction

Live regions (for example a polite status or a timer) tell screen readers when content changes. Sometimes you want only the changed digits announced; sometimes you want the whole region re-read so the update makes sense in context.

That choice is aria-atomic. The DOM property ariaAtomic lets you read and update the same value from JavaScript without calling setAttribute by hand.

const clock = document.getElementById("clock");
console.log(clock.ariaAtomic); // e.g. "true"
clock.ariaAtomic = "false";

Understanding the Property

MDN: the ariaAtomic property of the Element interface reflects the value of the aria-atomic attribute, which indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the aria-relevant attribute.

• Reflected attribute — mirrors aria-atomic.
• Get / set — readable and writable string.
• Live regions — typically used with aria-live.
• Baseline — widely available since October 2023 (MDN).

📝 Syntax

ariaAtomic

Value

A string with one of the following values:

📢 Pairing with aria-live

MDN’s example uses a timer live region. Atomic controls how much is spoken; live controls whether / how urgently updates are announced.

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

Examples Gallery

Examples follow MDN Element: ariaAtomic. Try-it labs create a small live-region element so you can read and write the property safely.

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

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

true

let el = document.getElementById("clock");
console.log(el.ariaAtomic); // true
el.ariaAtomic = "false";
console.log(el.ariaAtomic); // false

true
false

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

status.ariaAtomic = "true";
console.log({
  ariaAtomic: status.ariaAtomic,
  attr: status.getAttribute("aria-atomic")
});

{
  "ariaAtomic": "true",
  "attr": "true"
}

const el = document.createElement("div");
el.setAttribute("aria-live", "polite");
el.setAttribute("aria-atomic", "true");
document.body.appendChild(el);

el.ariaAtomic = "false";
console.log({
  fromProperty: el.ariaAtomic,
  fromAttribute: el.getAttribute("aria-atomic"),
  same: el.ariaAtomic === el.getAttribute("aria-atomic")
});

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

const sample = document.createElement("div");
sample.setAttribute("aria-atomic", "true");
console.log({
  supported: "ariaAtomic" in Element.prototype,
  sampleValue: sample.ariaAtomic,
  tip: "Use string \"true\" / \"false\" with live regions (aria-live)",
  status: "Baseline Widely available (MDN)"
});

{
  "supported": true,
  "sampleValue": "true",
  "tip": "Use string \"true\" / \"false\" with live regions (aria-live)",
  "status": "Baseline Widely available (MDN)"
}

🚀 Common Use Cases

• Timers and clocks that should be announced as a full labeled phrase.
• Status messages where only the changed sentence fragment should be spoken.
• Toggling atomic behavior when a live region’s structure changes.
• Keeping script and markup in sync without manual setAttribute.
• Teaching how aria-live, aria-atomic, and aria-relevant work together.

🔧 How It Works

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available).
• Values are the strings "true" and "false".
• Works with live regions—pair thoughtfully with aria-live.
• Related: ariaActiveDescendantElement, activeViewTransition, EventTarget, JavaScript hub.

💡 Best Practices