ARIA Live Politeness Settings

When content on a web page changes dynamically, sighted users perceive the update instantly. A form validation error appears in red, a chat message slides into view, a stock ticker refreshes. Screen reader users have no equivalent visual cue. They depend on the browser and assistive technology to detect the change and speak it aloud. The aria-live attribute, placed on a container element, tells the screen reader what to do when the content inside that container changes: interrupt immediately, wait for a natural pause, or say nothing at all.

The attribute accepts one of three values: off, polite, or assertive. Each value sets a different level of urgency for the announcement. Picking the right one requires thinking about how disruptive the change is and how time sensitive the information is. A search result count updating as the user types calls for patience; a session timeout warning calls for an immediate interruption.

Why ARIA live politeness settings matter

Modern web applications are full of content that changes without a page reload: toast notifications, inline validation errors, real-time collaboration indicators, loading spinners, countdown timers, and autocomplete suggestions. Without live regions, screen reader users have no way to know that any of these changes happened. They would need to manually navigate to every region of the page and check for new content, which is impractical and sometimes impossible when changes are frequent.

Choosing the wrong politeness level introduces different problems. Marking every update as assertive causes the screen reader to interrupt the user on every change, making it difficult to read other content or even finish typing. Marking a critical error as polite means the user might submit a broken form before hearing about the error, because the announcement waited in a queue behind other speech output.

WCAG 2.1 Success Criterion 4.1.3 (Status Messages) requires that status messages be programmatically determined so assistive technologies can present them without receiving focus. Live regions are the primary technique for meeting this requirement. Getting the politeness level wrong can cause a site to fail this criterion even when a live region is technically present.

How ARIA live politeness settings work

The three values of aria-live

off is the default. The screen reader does not announce changes to the region. Users can still navigate to the content manually and read it, but no proactive announcement is made. This is appropriate for content that updates very frequently, like a clock display or a streaming log, where constant announcements would be overwhelming.

polite tells the screen reader to queue the announcement and deliver it after it finishes its current speech output or after the user pauses. This is the right choice for most non-urgent updates: status messages ("3 items in your cart"), search result counts, or informational notifications.

assertive tells the screen reader to interrupt whatever it is currently saying and announce the new content immediately. This should be reserved for time sensitive or critical information: error alerts, session expiration warnings, or destructive-action confirmations.

Supporting attributes

Three companion attributes give finer control over how live region changes are communicated.

aria-atomic determines whether the screen reader announces the entire region or only the nodes that changed. When set to true, the full text content of the container is read on every update. When set to false (the default), only the changed portions are read. Setting aria-atomic="true" is useful when the changed fragment would be meaningless on its own, such as updating a single number inside a sentence.

aria-relevant specifies which types of DOM mutations trigger an announcement. Accepted tokens are additions, removals, text, and all. The default is additions text, which covers new nodes being added and text content changing. Adding removals causes the screen reader to announce when nodes are removed from the region.

aria-busy signals that the region is in the middle of a batch update. When set to true, the screen reader holds off on announcements. Set it back to false when the update is complete, and the screen reader will then announce the final state.

Implicit live regions

Some ARIA roles carry built-in live region semantics. An element with role="alert" implicitly behaves as aria-live="assertive" with aria-atomic="true". An element with role="status" behaves as aria-live="polite". An element with role="log" behaves as aria-live="polite" with aria-relevant="additions". When using these roles, you do not need to add aria-live explicitly, though doing so is harmless.

The container must exist first

A common mistake is creating the live region container and its content at the same time. Many screen readers only detect mutations on containers that already exist in the DOM. If both the <div aria-live="polite"> and its text are injected in a single operation, the screen reader may not register the change. The container should be present in the HTML from page load (or at least before the content is inserted).

Code examples

Bad example: no live region on a dynamic status message

<form>
  <label for="email">Email</label>
  <input type="email" id="email">
  <button type="submit">Subscribe</button>
  <div id="status-message"></div>
</form>

<script>
  document.querySelector("form").addEventListener("submit", (e) => {
    e.preventDefault();
    document.getElementById("status-message").textContent =
      "You have been subscribed successfully.";
  });
</script>

The confirmation text appears visually, but the <div> has no aria-live attribute. Screen readers will not announce the message. The user has no indication that the form submission succeeded.

Bad example: assertive on a frequently updating region

<div aria-live="assertive" id="search-count"></div>

<script>
  searchInput.addEventListener("input", () => {
    document.getElementById("search-count").textContent =
      results.length + " results found";
  });
</script>

Because assertive interrupts the current speech output, every keystroke cuts off whatever the screen reader was saying. The user cannot read other page content while typing.

Good example: polite live region with debouncing

<label for="search">Search articles</label>
<input type="text" id="search">
<div aria-live="polite" aria-atomic="true" id="search-count"></div>

<script>
  const searchInput = document.getElementById("search");
  let debounceTimer;
  searchInput.addEventListener("input", () => {
    clearTimeout(debounceTimer);
    debounceTimer = setTimeout(() => {
      const count = getFilteredResults().length;
      document.getElementById("search-count").textContent =
        count + " results found";
    }, 500);
  });
</script>

The polite value lets the screen reader finish its current output before announcing the count. aria-atomic="true" ensures the full sentence ("12 results found") is read rather than just the number. Debouncing prevents rapid-fire updates while the user is still typing.

Good example: assertive alert for a session timeout

<div role="alert" id="error-banner"></div>

<script>
  function showCriticalError(message) {
    document.getElementById("error-banner").textContent = message;
  }

  showCriticalError(
    "Your session will expire in 60 seconds. Save your work now."
  );
</script>

role="alert" implies aria-live="assertive" and aria-atomic="true", so the screen reader interrupts immediately to deliver the warning. The container is already in the DOM before the text is injected, which is necessary for reliable detection across browsers and screen readers.