JavaScript Document ariaNotify() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method
Decorative image with the word ARIANOTIFY

Definition

document.ariaNotify() queues a string for a screen reader to announce. Unlike classic live regions, you can announce at any time — the message does not need a DOM update first.

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call document.ariaNotify. Start with this line.

JavaScript
document.ariaNotify(msg[, options])
CallWhat it does
document.ariaNotify(msg[, options])Primary signature.
document.ariaNotify(...)Call with the arguments your case needs.

Built into the browser. Call ariaNotify(...) on document — no import required.

Library declarations
JavaScript
document.ariaNotify(msg[, options])

Parameters

ParameterDescription
announcementRequired. Text the screen reader should speak
options.priorityOptional. "normal" (default) or "high"

Return Value

Return ValueDescription
*Always undefined

JavaScript Examples

Example 1 — Announce on Button Click

MDN-style: queue a document-level announcement when the user presses a button.

JavaScript
document.querySelector("button").addEventListener("click", () => {
  if (typeof document.ariaNotify === "function") {
    document.ariaNotify("Hi there, I'm Ed Winchester.");
  }
});
Try It Yourself

How It Works

  1. Listen for click. The announcement runs when the user activates the button.
  2. Feature-detect. Avoid calling a missing method on older browsers.
  3. Queue the string. ariaNotify hands the text to the accessibility layer.
  4. Return value. The call returns undefined — success is hearing the speech, not a return code.

Example 2 — High-Priority Status Update

Use priority: "high" for urgent feedback (like MDN’s shopping-list remove).

JavaScript
const item = "Apples";
const total = 4.5;

if (typeof document.ariaNotify === "function") {
  document.ariaNotify(
    `${item} removed. Total is now £${total.toFixed(2)}.`,
    { priority: "high" }
  );
}
Try It Yourself

How It Works

  1. Build one sentence. Item name and new total are combined — more reliable than two calls.
  2. Pass options. { priority: "high" } asks to interrupt current speech.
  3. Like assertive live regions. MDN maps high ≈ aria-live="assertive".
  4. Use sparingly. High priority should be for important status, not every hover.

Example 3 — Feature Detect with Live-Region Fallback

Keep an aria-live path for browsers without ariaNotify.

JavaScript
function announce(msg) {
  if (typeof document.ariaNotify === "function") {
    document.ariaNotify(msg);
    return "ariaNotify";
  }
  const live = document.getElementById("live");
  live.textContent = "";
  live.textContent = msg;
  return "aria-live";
}

console.log(announce("Saved successfully."));
Try It Yourself

How It Works

  1. Prefer ariaNotify. If the function exists, use it.
  2. Else update a live region. Clearing then setting textContent retriggers polite announcements.
  3. Return which path ran. Handy for demos and tests.
  4. Progressive enhancement. Users still get feedback when the newer API is absent.
Compatibility

Browser Support

Document.ariaNotify() is a browser accessibility API. MDN marks it Baseline 2026 Newly available (since September 2026). Older browsers may lack it — feature-detect and keep an aria-live fallback.

✓ Baseline 2026 · Newly available

Document.ariaNotify()

Supported in the latest major browsers. Not available in Internet Explorer. Always detect before calling.

New Baseline 2026
Google Chrome Latest (Baseline 2026)
Yes
Microsoft Edge Latest (Baseline 2026)
Yes
Mozilla Firefox Latest (Baseline 2026)
Yes
Apple Safari Latest (Baseline 2026)
Yes
Opera Latest (Baseline 2026)
Yes
Internet Explorer No
No
ariaNotify() Newly available

Bottom line: Use with feature detection. Prefer one clear message; keep aria-live as a fallback. See the MDN ariaNotify() reference.

Frequently Asked Questions

It queues a string of text for a screen reader to announce. Unlike classic ARIA live regions, you can call it at any time — the message does not have to come from a DOM content change.
No. MDN marks it as Baseline 2026 Newly available (since September 2026). It is not Deprecated, Experimental, or Non-standard. Older browsers may still lack it — always feature-detect.
priority: "normal" (default) waits until the screen reader finishes its current speech. priority: "high" interrupts and speaks immediately. Roughly like aria-live polite vs assertive.
undefined. There is no promise or status object. If Permissions Policy blocks aria-notify, the call fails silently.
Some screen readers may only speak the most recent ariaNotify() call. One combined message is more reliable than several quick calls in a row.
Fall back to an ARIA live region (update text on an element with aria-live). Feature-detect first: typeof document.ariaNotify === "function".

Next: browsingTopics()

Continue with the next Document method in the tutorial series.

browsingTopics() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

16 people found this page helpful

JavaScript Document append() Method JavaScript Document browsingTopics() Method