Element: ariaNotify() method

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

Non-standard: This feature is not standardized. We do not recommend using non-standard features in production, as they have limited browser support, and may change or be removed. However, they can be a suitable alternative in specific cases where no standard option exists.

The ariaNotify() method of the Element interface specifies that a given string of text should be announced by a screen reader if available and activated.

Syntax

ariaNotify(announcement)
ariaNotify(announcement, options)

Parameters

announcement

A string specifying the text to be announced.

options Optional

An options object containing the following properties:

priority

An enumerated value specifying the priority of the announcement. Possible values are:

normal: The announcement has normal priority. It will be spoken after any announcement that a screen reader is currently making.
high: The announcement has high priority. It will be spoken immediately, interrupting any announcement that a screen reader is currently making.

Return value

None (undefined).

Description

The ariaNotify() method can be used to programmatically trigger a screen reader announcement. This method provides similar functionality to ARIA live regions, with some advantages:

Live regions can only make announcements following changes to the DOM, whereas an ariaNotify() announcement can be made at any time.
Live region announcements involve reading out the updated content of the changed DOM node, whereas ariaNotify() announcement content can be defined independently of DOM content.

Developers often work around the limitations of live regions using hidden DOM nodes with live regions set on them, which have their contents updated with the content to be announced. This is inefficient and error-prone, and ariaNotify() provides a way to avoid such issues.

Some screen readers will read out multiple ariaNotify() announcements in order, but this cannot be guaranteed across all screen readers and platforms. Normally, only the most recent announcement is spoken. It is more reliable to combine multiple announcements into one.

For example, the following calls:

elemRef.ariaNotify("Hello there.");
elemRef.ariaNotify("The time is now 8 o'clock.");

would be better combined:

elemRef.ariaNotify("Hello there. The time is now 8 o'clock.");

An ariaNotify() call can be fired on any element in the DOM, except for ones that the browser does not consider "interesting" for accessibility, and ignores when building the accessibility tree. Exactly which elements are ignored varies by browser, but the list generally includes container elements of little to no semantic value, such as the <html> and <body> elements.

ariaNotify() announcements do not require transient activation; you should take care not to spam screen reader users with too many notifications, as this could create a bad user experience.

Announcement priorities

An ariaNotify() announcement with priority: high set is announced before an ariaNotify() announcement with priority: normal set.

ariaNotify() announcements are roughly equivalent to ARIA live region announcements as follows:

ariaNotify() priority: high: aria-live="assertive".
ariaNotify() priority: normal: aria-live="polite".

However, aria-live announcements will take priority over ariaNotify() announcements.

Language selection

Screen readers choose an appropriate voice with which to read ariaNotify() announcements (in terms of accent, pronunciation, etc.) based on the language specified in the element's lang attribute or, if the element does not have a specified lang attribute, the lang attribute set on its nearest ancestor. If there is no lang attribute specified in the HTML, the user agent's default language is used.

<button>Press</button>

html,
body {
  height: 100%;
}

body {
  display: flex;
  justify-content: center;
  align-items: center;
}

document.querySelector("button").addEventListener("click", () => {
  document.querySelector("button").ariaNotify("You ain't seen me, right?");
});

Result

The output is as follows:

Try activating a screen reader and then pressing the button. You should hear "You ain't seen me, right?" spoken by the screen reader.

Specifications

This feature does not appear to be defined in any specification.

Browser compatibility

Help improve MDN

Learn how to contribute

This page was last modified on ⁨Jan 1, 1970⁩ by MDN contributors.

View this page on GitHub • Report a problem with this content