mgifford/accessibility-skills/aria-live-regions

ARIA Live Regions Accessibility Skill

Canonical source: examples/ARIA_LIVE_REGIONS_BEST_PRACTICES.md in mgifford/ACCESSIBILITY.md

This skill is derived from that file. When in doubt, the example is authoritative.

Apply these rules when implementing any dynamic content updates announced to assistive technologies. Only load this skill if the project contains dynamic content updates.

Core Mandate

Live regions make dynamic status information available to screen reader users without moving keyboard focus — they are useful for concise updates (a result count, a saved confirmation, progress information). Live regions are not a general notification system. They do not replace visible content, native HTML, focus management, or a control's programmatic state. Poorly timed or excessive announcements can be missed, duplicated, reordered, or disruptive.

Prefer visible status messages — they also help magnification users, cognitive/learning-disabled users, and anyone who wouldn't otherwise notice a change elsewhere on the page. Use native HTML and programmatic control state (e.g., aria-expanded) before reaching for a live region.

Severity Scale (this skill)

What WCAG 4.1.3 Actually Requires

WCAG 4.1.3 requires existing status messages to be programmatically determinable so AT can present them without moving focus. It does not require creating a new status message for every dynamic change — an updated result list is content; a message like "18 results found" is the status message. A dialog receiving focus is a change of context, not a status message.

Choose the mechanism by situation, not by default reflex:

Live regions can supplement focus management — they should not announce a focus change that already provides the same information.

Critical: role="status", role="alert", and role="log"

<p id="cart-status" role="status"></p>
<p id="connection-alert" role="alert"></p>

Do not add redundant explicit aria-live/aria-atomic values on these roles unless a verified compatibility need justifies it. An alert does not receive focus and should not require a response to dismiss — if the user must stop and respond, use the [ARIA APG alert dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/) with full modal dialog keyboard handling instead. Do not use role="alert" for routine validation, success confirmations, or every field error.

<div role="log" aria-relevant="additions" aria-atomic="false">
  <p>Jordan uploaded quarterly-report.pdf.</p>
</div>

role="log" needs an accessible name (via a heading + aria-labelledby) and each entry should be understandable on its own.

`aria-live` bare values (use only when no live-region role fits):

assertive indicates priority but does not guarantee any specific AT will interrupt speech immediately — actual behavior depends on product, settings, and other queued output. Using `assertive`/`role="alert"` for non-urgent updates is Serious.

Serious: aria-atomic, aria-relevant, and aria-busy

`aria-atomic` (default false): use true when the complete phrase provides necessary context ("3 items in cart"); use false when each addition is independently meaningful (a new chat log entry). status/alert already default to true. When true, the region's accessible name/label may also be presented — test the resulting full phrase, not just the changed text node.

<div role="status" aria-atomic="true" id="filter-status">
  Showing 24 of 156 results for "accessible forms"
</div>

`aria-relevant` — its default is `additions text`, not just additions. Values: additions, removals, text, all. These are suggestions to AT, not delivery guarantees. Use removals/all sparingly — don't rely on removal announcements for critical information.

`aria-busy` — set true while a region receives a batch of related updates, then reset to false when complete. AT may defer processing until the region is no longer busy.

results.setAttribute('aria-busy', 'true');
renderResults(items);
results.setAttribute('aria-busy', 'false');

Always reset `aria-busy`, including after an error — leaving it true after an exception is a common failure. Don't use aria-busy as the only loading indication; provide visible status too.

Critical: Update Timing — No Fixed-Delay Workarounds

Live-region behavior depends on accessibility APIs observing the region before the relevant content change — adding a live region and its completed message in the same DOM operation may be missed. The useful rule: expose a stable live region first, then update its content in response to a later event. The region does not need to exist on initial page load — in a component/SPA it can mount before a later update, as long as it's mounted before that update happens. If users must understand information on initial load, put it visibly in the reading order instead of relying on a live region.

No standard defines a reliable 50ms, 100ms, or any other fixed delay for live regions. Clearing a region and reinserting the same text after a timeout can produce missed, duplicate, stale, or reordered output — do not use this pattern. Instead:

• keep a stable announcement node
• update it after the component has mounted
• let the framework render the message from state
• announce only the final meaningful result of a rapid sequence
• suppress responses from stale asynchronous requests
• use a tested application-announcer abstraction when many components report status

role="alert" has special processing in many implementations, so dynamically rendered alert content is often announced — this does not make alert equivalent to adding aria-live="assertive" to any new element, and does not make initial-page-load alerts reliable.

Serious: Visibility and Content Scope

Use a visually hidden live region only when: equivalent visible information already exists and a nonvisual supplement is genuinely needed, or a concise announcement is needed to describe a complex visible update. Do not duplicate the same message in both a visible and a separate hidden live region — that causes repeated announcements.

.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;
}

Never apply `hidden`, `display: none`, `visibility: hidden`, or `aria-hidden="true"` to a live region while it's expected to announce — avoid rules like .status:empty { display: none; } when the empty region must stay exposed before its next update.

Keep the live region narrow — announce the short status, not an entire results container, form, table, or page section. Avoid nested live regions and avoid a role="alert" inside another live region. Interactive controls generally don't belong inside a live region; if a toast contains an action, keep it persistent long enough to find and operate, with its own focus strategy.

Implementation Patterns

Visible status after an action:

<button type="button" id="add-to-cart">Add notebook to cart</button>
<p id="cart-status" role="status"></p>

addButton.addEventListener('click', () => {
  addProduct('Notebook');
  cartStatus.textContent = 'Notebook added to cart. 3 items in cart.';
});

Search results with stale-request handling:

let requestSequence = 0;
searchForm.addEventListener('submit', async (event) => {
  event.preventDefault();
  const sequence = ++requestSequence;
  results.setAttribute('aria-busy', 'true');
  resultStatus.textContent = `Searching for ${query}.`;
  try {
    const items = await searchProducts(query);
    if (sequence !== requestSequence) return; // stale response, ignore
    renderSearchResults(results, items);
    resultStatus.textContent = `${items.length} results found for ${query}.`;
  } catch (error) {
    if (sequence === requestSequence) {
      resultStatus.textContent = 'Search could not be completed. Try again.';
    }
  } finally {
    if (sequence === requestSequence) results.setAttribute('aria-busy', 'false');
  }
});

Escape/render untrusted result data safely. Consider delaying the visible "Searching" message so fast operations don't announce both loading and completion in immediate succession.

Character count — announce only at thresholds, not every keystroke:

const thresholds = new Set([100, 50, 20, 10, 0]);
let lastAnnounced = null;
summary.addEventListener('input', () => {
  const remaining = summary.maxLength - summary.value.length;
  remainingCount.textContent = remaining; // visible count updates continuously
  if (thresholds.has(remaining) && remaining !== lastAnnounced) {
    countStatus.textContent = `${remaining} characters remaining.`; // hidden status, threshold only
    lastAnnounced = remaining;
  }
});

Form errors: show a visible summary and move focus to it — this is a focus-management pattern, a live region is not required for the summary itself. Do not add role="alert" to every field error while the user is typing; a concise nearby role="status" may suit a single async field check if it doesn't duplicate what focus already presented.

Progress: use native <progress>; announce meaningful milestones or completion, not every percentage change.

Session timeout requiring a response: use an alert dialog (role="alertdialog", aria-modal="true", accessible name/description, initial focus inside, keyboard containment, focus returned on close) — an assertive announcement alone does not make a timed interaction accessible. Follow WCAG 2.2.1 Timing Adjustable for the timeout itself.

Moderate: Managing Multiple Updates

Rapid live-region updates can overwhelm the speech queue and hide the outcome the user needs: