← Back to Accessalyze

What Is aria-live and When to Use It?

Single-page apps, search-as-you-type, form validation, notifications, countdown timers, shopping cart updates — modern web UIs change content dynamically without full page loads. Sighted users see these changes visually. Screen reader users miss them entirely unless you use aria-live.

The Three aria-live Values

Use assertive sparingly. Interrupting a screen reader mid-sentence is highly disruptive. Most use cases are polite.

Shorthand Roles: role="status" and role="alert"

These roles are equivalent to live regions with preset behavior:

<!-- role="status" = aria-live="polite" + aria-atomic="true" -->
<div role="status">Your preferences have been saved.</div>

<!-- role="alert" = aria-live="assertive" + aria-atomic="true" -->
<div role="alert">Error: Payment failed. Please try again.</div>

Setup: Declare the Region on Page Load

The most important rule: declare the live region in the DOM before you put content in it. Screen readers register live regions when the page loads. If you inject the aria-live container and the content at the same time, many screen readers miss the announcement.

<!-- In your HTML on page load (empty) -->
<div id="status-region" role="status" aria-live="polite" aria-atomic="true"></div>

<script>
// Later — update the region's content
document.getElementById('status-region').textContent = '12 results found';
</script>

Common Patterns

Search Results Count

<!-- HTML (on page load, empty) -->
<p role="status" aria-live="polite" id="search-count"></p>

<script>
// After search results render
document.getElementById('search-count').textContent =
  `${results.length} results for "${query}"`;
</script>

Form Success Message

<!-- Empty container in HTML -->
<div role="status" id="form-feedback"></div>

<script>
async function submitForm(e) {
  e.preventDefault();
  await saveData();
  const feedback = document.getElementById('form-feedback');
  feedback.textContent = 'Your profile has been updated successfully.';
}
</script>

Validation Error Alert

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

<script>
function showErrors(errors) {
  document.getElementById('error-region').innerHTML =
    `<p>Please fix ${errors.length} error(s):</p>
     <ul>${errors.map(e => `<li>${e}</li>`).join('')}</ul>`;
}
</script>

Shopping Cart Update

<span role="status" id="cart-status" class="sr-only"></span>

<script>
function addToCart(product) {
  cart.add(product);
  document.getElementById('cart-status').textContent =
    `${product.name} added to cart. Cart now has ${cart.count} items.`;
}
</script>

aria-atomic and aria-relevant

aria-atomic="true" (default on role="status"/role="alert") means the entire region is announced when any part changes — not just the changed portion. Use this for most cases.

aria-relevant lets you specify which changes trigger announcements: "additions", "removals", "text", or "all". The default is "additions text". Rarely needed.

WCAG 4.1.3 Status Messages

WCAG 2.1 criterion 4.1.3 (Level AA) requires that status messages — "Form saved", "3 errors found", "Item added to cart" — be programmatically determinable without receiving focus. This is exactly what aria-live and role="status"/role="alert" provide.

← Back to Accessalyze