Imperatively Notify Assistive Technologies with the `ariaNotify()` Method

The ariaNotify() method is a Web API that provides an imperative way to notify users of assistive technologies about dynamic content updates. Traditional WAI-ARIA patterns usually conveyed information to assistive technologies through declarative attributes such as aria-label="xxx" or aria-checked="true". In contrast, ariaNotify() is notable because it lets JavaScript send a notification at a specific moment.

The ariaNotify() method is intended for scenarios such as the following.

• Announcing when a new message arrives in a chat app, especially when you want to notify the user only after AI-generated output is complete
• Announcing when a participant joins or leaves a video conferencing app
• Announcing that an item was added to a shopping cart, because a user without a visual impairment may notice the cart icon changing while a user relying on assistive technology needs an explicit notification
• Events not tied to a DOM change, such as formatting changes like making text bold with Ctrl+B
• Announcing the contents of a new page after navigation in an SPA (Single Page Application)

Traditionally, for use cases like these, developers often created a DOM element with the aria-live attribute and used it to send notifications to assistive technologies. For example, when adding an item to a shopping cart, the code might look like this.

<!-- aria-live="polite" instructs assistive technologies to notify the user when the content changes -->
<!-- If the notification must interrupt the user's current action, prepare a separate aria-live="assertive" element -->
<div
  id="live-region"
  role="status"
  aria-live="polite"
  aria-atomic="true"
  class="visually-hidden"
></div>
 
<button id="add-btn">Add to cart</button>
 
<style>
  /* visually-hidden hides content visually */
  /* display: none; also hides it from assistive technologies, so positioning it off-screen is a common approach */
  .visually-hidden {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    white-space: nowrap;
    border: 0;
  }
</style>
 
<script>
  const liveRegion = document.getElementById("live-region");
 
  function announce(message) {
    // A common hack: clear the text once and set it again with setTimeout
    // so the same string can still be re-announced
    liveRegion.textContent = "";
    setTimeout(() => {
      liveRegion.textContent = message;
    }, 100);
  }
 
  document.getElementById("add-btn").addEventListener("click", () => {
    // ...process for adding the item to the cart...
    announce("Item added to cart. 3 items.");
  });
</script>

In the example above, an element with aria-live="polite" is prepared, and the JavaScript announce function updates its content so assistive technologies can announce it. However, this approach had several problems.

• It increases implementation complexity because you need visually hidden elements and sometimes hacks like clearing and re-setting text
• Even when the DOM is updated, the change may not be conveyed correctly to assistive technologies. For example, if a shared live region is placed at the end of the DOM and managed as a singleton across the whole site, notifications may fail while a modal dialog is open. Live region implementations also differ across browsers and screen readers, so the same code may behave differently depending on the environment (for details, see Improving Notification Handling with AriaNotify)
• The timing of polite and assertive announcements depends on the assistive technology implementation, so notifications do not always occur exactly when intended

The ariaNotify() method was designed to solve these problems. Because it lets JavaScript send a notification at a specific time, it provides a more flexible and reliable way to communicate dynamic content changes.

This article explains how to use the ariaNotify() method, including implementation examples and important caveats.

How to use the ariaNotify() method

The ariaNotify() method is defined on Element.prototype, so it can be called from any element. Because Document also shares the same interface as a ParentNode, calling it on document is the simplest approach.

document.ariaNotify("Ibuki has joined the room.");

Running this code sends the notification "Ibuki has joined the room." to users of assistive technologies. The ariaNotify() method was intentionally designed as a write-only API, so there is no way to determine from a return value whether the notification was actually delivered. This is a design decision intended to prevent it from being abused for fingerprinting.

Depending on the assistive technology, multiple ariaNotify() calls may sometimes be read in order, but that behavior is not guaranteed by the specification. In general, only the latest notification is likely to be read, so one combined call is more reliable than multiple separate calls.

// If called consecutively, only the final notification is likely to be read
document.ariaNotify("Item added to cart");
document.ariaNotify("3 items.");
 
// Combining it into one call is more reliable
document.ariaNotify("Item added to cart. 3 items.");

Specify notification priority

You can specify the priority of the notification using the options object in the second argument. There are two values: priority: "high" and priority: "normal" (the default). These are roughly equivalent to aria-live="assertive" and aria-live="polite" respectively.

// Example of sending a high-priority notification
document.ariaNotify("An error occurred, so the data could not be saved.", {
  priority: "high",
});

Language selection

When assistive technologies read a notification sent with ariaNotify(), they refer to the <html> element's lang attribute, which affects things like pronunciation and accent. If the lang attribute is not present, they fall back to the user's browser language settings. Therefore, if you want a notification to be read in a specific language, you should make sure the lang attribute is set appropriately.

<!-- If you want the notification to be read in Japanese -->
<html lang="ja">
  ...
</html>
 
<script>
  // It will be read with Japanese pronunciation and accent
  document.ariaNotify("商品をカートに追加しました。3点。");
</script>

Example: adding an item to a shopping cart

Let's look at a concrete example using the ariaNotify() method. We will implement the shopping cart example described earlier with ariaNotify(). Compared with the traditional aria-live approach, the code becomes much simpler.

<button id="add-btn">Add to cart</button>
 
<script>
  document.getElementById("add-btn").addEventListener("click", () => {
    // ...process for adding the item to the cart...
    document.ariaNotify("Item added to cart. 3 items.");
  });
</script>

When I tried this with VoiceOver on macOS, I confirmed that clicking the "Add to cart" button caused VoiceOver to announce, "Item added to cart. 3 items." (tested in Chrome Canary 149).

Summary

• The ariaNotify() method is a Web API that provides an imperative way to notify users of assistive technologies about dynamic content updates
• The traditional approach was to add a DOM element with aria-live, but that came with problems such as implementation complexity and uncertainty around notification timing
• Because ariaNotify() lets JavaScript send notifications at the exact moment you choose, it can communicate updates with simpler code
• You can control notification priority, but excessive use can create an annoying experience for users, so it should be used carefully

References

• Accessible Rich Internet Applications (WAI-ARIA) 1.3
• Element: ariaNotify() method - Web APIs | MDN
• WICG/accessible-notifications: ARIA Accessible Notifications
• Improving Notification Handling with AriaNotify
• Understanding Success Criterion 4.1.3: Status Messages | WAI | W3C
• aria-live - ARIA | MDN
• ARIA Notifyについて - Speaker Deck