Element.ariaNotify() is an instance method that queues text for a screen reader to announce. Learn priorities, how it compares to ARIA live regions, feature detection, and five try-it labs. Support is Limited availability (not Baseline yet).
Instance method
Screen reader text
normal / high
undefined
No DOM change needed
Limited availability
Classic accessible status updates often use an ARIA live region: put aria-live on an element and change its text so assistive tech announces it. That only works when the DOM content changes—and many apps hide extra nodes just to trigger speech.
ariaNotify() lets you request an announcement directly from JavaScript, with a message that can be independent of what is visible on the page. It is part of the WAI-ARIA ARIANotifyMixin (also available on Document).
You will only hear announcements if a screen reader (or similar AT) is active. Always feature-detect, and keep an aria-live fallback for browsers without the method.
This page is part of JavaScript Element. Related topics include append() and ariaLive.
ariaNotify() MethodCalling el.ariaNotify(text) queues text for assistive technology. It does not change the element’s visible content by itself.
Element (and Document).<html> / <body>).General forms of Element.ariaNotify (MDN):
ariaNotify(announcement)
ariaNotify(announcement, options)priority — "normal" (default: spoken after the current announcement) or "high" (interrupt and speak immediately).None (undefined).
priority: "high" ≈ aria-live="assertive"priority: "normal" ≈ aria-live="polite"aria-live announcements still take priority over ariaNotify().btn.ariaNotify("Saved successfully.");
btn.ariaNotify("Error: try again.", { priority: "high" });
// Prefer one combined message
btn.ariaNotify("Hello there. The time is now 8 o'clock.");
if (typeof el.ariaNotify === "function") {
el.ariaNotify("Ready");
}| Goal | Code |
|---|---|
| Announce text | el.ariaNotify("Done") |
| Urgent interrupt | el.ariaNotify(msg, { priority: "high" }) |
| Feature-detect | typeof el.ariaNotify === "function" |
| Fallback | Update an aria-live region |
| Language voice | Set lang on el or an ancestor |
| MDN / BCD status | Limited availability; not Deprecated / Experimental / Non-standard |
Four facts to remember about Element.ariaNotify().
undefinedQueues speech only
limitedNot Baseline yet
yesScreen reader hears it
not requiredUnlike live regions
ariaNotify() vs ARIA live regionsel.ariaNotify(msg) | aria-live region | |
|---|---|---|
| Trigger | Any time from JS | After DOM content changes |
| Message source | Argument string | Updated node text / content |
| Hidden live node hack | Not needed | Often used as a workaround |
| Urgency | priority normal / high | polite / assertive |
| Browser support | Limited / rolling out | Widely available |
| Best for | JS events without DOM text updates | Cross-browser status text today |
Examples follow MDN Element.ariaNotify() patterns. Use a screen reader in supporting browsers to hear announcements. View Output shows what the script does on screen.
MDN-style button announce, plus safe feature detection.
ariaNotify() (MDN)Click a button to queue a screen reader announcement on itself.
document.querySelector("button").addEventListener("click", () => {
document.querySelector("button").ariaNotify("You ain't seen me, right?");
});The announcement is queued from the button element. Visible UI does not need to change for AT to speak the string (when the API and a screen reader are available).
Always check the method exists before calling it.
const btn = document.querySelector("button");
if (typeof btn.ariaNotify === "function") {
btn.ariaNotify("Notification sent.");
console.log("ariaNotify supported");
} else {
console.log("ariaNotify not supported — use aria-live fallback");
}Limited availability means many browsers still lack the method. Detection avoids TypeError and keeps your UX progressive.
High priority, combining messages, and a live-region fallback.
priority: "high"Interrupt-style announcements for urgent errors (like assertive live regions).
const form = document.getElementById("form");
form.addEventListener("submit", (e) => {
e.preventDefault();
if (typeof form.ariaNotify === "function") {
form.ariaNotify("Error: email is required.", { priority: "high" });
}
});High priority aims to speak immediately. Use sparingly so you do not constantly interrupt the user.
Prefer one string over back-to-back calls.
const status = document.getElementById("status");
// Less reliable across AT:
// status.ariaNotify("Hello there.");
// status.ariaNotify("The time is now 8 o'clock.");
// Better — one announcement
if (typeof status.ariaNotify === "function") {
status.ariaNotify("Hello there. The time is now 8 o'clock.");
}MDN notes that some screen readers may only speak the latest call. Combining keeps the full message together.
Progressive enhancement when ariaNotify is missing.
function announce(el, message) {
if (typeof el.ariaNotify === "function") {
el.ariaNotify(message);
return;
}
const live = document.getElementById("live");
live.textContent = "";
// Force a change so polite live regions re-announce
requestAnimationFrame(() => {
live.textContent = message;
});
}
announce(document.getElementById("action"), "Item added to cart.");Supporting browsers use the modern API; others still get an accessible update through a polite live region.
priority: "high".Document.ariaNotify() when a document-level announce is clearer.ariaNotify() AnnouncesPass announcement text (and optional priority) from an Element in the a11y tree.
Permissions Policy may block silently; otherwise the string is queued for AT.
Voice/language follows lang on the element or nearest ancestor.
No promise—verify support and test with real assistive tech.
experimental: false, standard_track: true).aria-notify can block announcements silently.lang (or nearest ancestor / UA default).Element.ariaNotify() is Limited availability on MDN (not Baseline). Logos use the shared browser-image-sprite.png sprite from this project. Support is rolling out (for example full support in recent Firefox; partial in some Chromium builds). Always feature-detect.
Standard-track accessibility API. Keep an aria-live fallback until Baseline coverage improves.
Bottom line: Use ariaNotify() where supported for JS-driven announcements. Feature-detect and fall back to ARIA live regions for broad compatibility.
Element.ariaNotify() queues screen reader announcements without requiring a DOM text change. Prefer combined messages, use high priority sparingly, and always feature-detect with an aria-live fallback while support remains limited.
Continue with ariaLive, append(), or the JavaScript hub.
ariaNotifylang when language matters for pronunciationaria-notify blocksElement.ariaNotify()Queue AT speech from JS—feature-detect and fall back.
undefined
APIAT speech
A11ynormal / high
Urgencylimited
Statusaria-live
SafeThe same mixin powers Document.ariaNotify(). MDN’s shopping-list demo works the same if you call the method on an element reference instead of the document—choose the landmark that best matches the context of the announcement.
Browse Element methods and ARIA properties to keep building accessible UIs.
8 people found this page helpful