JavaScript Document ariaNotify() Method

What You’ll Learn

document.ariaNotify() is an instance method that queues text for a screen reader at the document level. Learn priorities, how it compares to ARIA live regions and Element.ariaNotify(), MDN’s shopping-list pattern, and five try-it labs. Support is Limited availability (not Baseline yet).

Introduction

Accessible status updates often use an ARIA live region: set aria-live on an element and change its text so assistive technology announces it. That only works when DOM content changes—and many apps maintain hidden nodes just to trigger speech.

MDN: Document.ariaNotify() queues a string of text to be announced by a screen reader. You can make announcements at any time, with message text independent of visible DOM content. The same ARIANotifyMixin is also available on Element.

Related tutorials: Element.ariaNotify(), append(), Document constructor.

Understanding document.ariaNotify()

Calling document.ariaNotify(text) queues text for assistive technology. It does not change visible page content by itself.

• It is an instance method on the live page’s document object.
• Announcements can happen without a DOM update (unlike live regions) (MDN).
• Message text is defined in the call—independent of node content (MDN).
• Prefer one combined string over several rapid calls (MDN).
• No transient activation required—avoid spamming screen reader users (MDN).
• Permissions Policy aria-notify can block usage silently (MDN).

📝 Syntax

General forms of Document.ariaNotify (MDN):

ariaNotify(announcement)
ariaNotify(announcement, options)

Parameters

• announcement — a string specifying the text to be announced (MDN).
• options (optional) — an object that may include:
  • priority — "normal" (default: spoken after current speech) or "high" (interrupt immediately) (MDN).

Return value

None (undefined).

Priority vs live regions (MDN)

• priority: "high" ≈ aria-live="assertive"
• priority: "normal" ≈ aria-live="polite"
• Existing aria-live announcements still take priority over ariaNotify() (MDN).

Common patterns

document.ariaNotify("Saved successfully.");

document.ariaNotify("Error: try again.", { priority: "high" });

// Prefer one combined message (MDN)
document.ariaNotify("Hello there. The time is now 8 o'clock.");

if (typeof document.ariaNotify === "function") {
  document.ariaNotify("Ready");
}

⚖️ Document.ariaNotify vs Element.ariaNotify vs live regions

Examples Gallery

Examples follow MDN Document: ariaNotify(). Use a screen reader in supporting browsers to hear announcements.

document.querySelector("button").addEventListener("click", () => {
  document.ariaNotify("Hi there, I'm Ed Winchester.");
});

(click Press — screen readers may announce: Hi there, I'm Ed Winchester.)

if (typeof document.ariaNotify === "function") {
  document.ariaNotify("Notification sent.");
  console.log("document.ariaNotify supported");
} else {
  console.log("Not supported — use aria-live fallback");
}

document.ariaNotify supported
  — or —
Not supported — use aria-live fallback

document.ariaNotify("Session expired. Please sign in again.", {
  priority: "high"
});

(may announce with high priority: Session expired. Please sign in again.)

// Less reliable across AT (MDN):
// document.ariaNotify("Hello there.");
// document.ariaNotify("The time is now 8 o'clock.");

// Better — one announcement
document.ariaNotify("Hello there. The time is now 8 o'clock.");

Hello there. The time is now 8 o'clock.

let total = 0;

form.addEventListener("submit", (e) => {
  e.preventDefault();
  total += Number(price.value);
  updateTotal();

  document.ariaNotify(
    `Item ${item.value}, price £${price.value}, added to list. Total is now £${total.toFixed(2)}.`,
    { priority: "high" }
  );
});

Item Milk, price £1.50, added to list. Total is now £1.50.
(screen reader may announce via document.ariaNotify)

🚀 Common Use Cases

• App-wide status — save, submit, or navigation feedback without a visible status node.
• Shopping / todo lists — MDN demo: announce item + running total on add/remove.
• Validation errors — priority: "high" for urgent messages.
• Replacing hidden live nodes — avoid off-screen aria-live hacks.
• When Element target is unclear — document-level announce for global events.
• Progressive enhancement — pair with aria-live fallback until Baseline coverage grows.

📝 Notes

• MDN: Limited availability (not Baseline)—feature-detect before production use.
• Not Deprecated, Experimental, or Non-standard — WAI-ARIA ARIANotifyMixin.
• Same API as Element.ariaNotify().
• Permissions Policy aria-notify can block announcements silently (MDN).
• Language/voice uses lang on the document element or UA default (MDN).
• Related: Element.ariaNotify(), append(), Document().

💡 Best Practices