Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 38 ยท Forms and Dynamic Content

Live Regions and Status Messages

Announce dynamic updates to screen readers with aria-live, role=status, role=alert and aria-atomic. Covers toasts, loading states, search results and common pitfalls.

Sighted users notice when something changes on screen: a "Saved" badge, "3 results found", a spinner turning into content. Screen reader users only hear what the screen reader announces, and by default it announces the element that has focus. If content changes elsewhere, nothing is said. Live regions fix that by telling assistive technology to announce changes in a particular container.

WCAG 4.1.3 Status Messages (AA) requires that status messages can be presented to users without receiving focus.

The three tools

Tool Equivalent Behavior Use for
aria-live="polite" role="status" Waits until the user is idle, then reads "Saved", "3 results", cart count
aria-live="assertive" role="alert" Interrupts at once Errors that block progress, session expiry
aria-live="off" default No announcement Everything else

role="status" implies aria-live="polite" and aria-atomic="true". role="alert" implies assertive and atomic. Use the roles; they are shorter and well supported.

Prefer polite. Interrupting someone mid-sentence is rude and disorienting. Reserve assertive for things the user must know now.

The golden rule: the region must already exist

Screen readers watch live regions for changes. If you insert a brand-new <div role="status"> together with its text in one step, many readers will say nothing, because the region did not exist before the change. So:

  1. Put an empty live region in the HTML on page load.
  2. Later, set its text (textContent = ...).
HTML
<div id="status" role="status"></div>
<script>
  document.getElementById('status').textContent = '3 results found';
</script>

role="alert" is the exception that often works when inserted, but do not depend on it.

Basic example: a save button

Polite status message

Turn on a screen reader (see screen reader testing) and press the button: it says "Draft saved (1 time)" while focus stays on the button.

Notice that the text changes each time. If the message is identical, some readers will not repeat it; changing a counter or clearing the region first then setting it again (after a tick) helps.

aria-atomic and aria-relevant

  • aria-atomic="true": announce the whole region, not just the changed part. Good for "Cart: 3 items" when only the number changes.
  • aria-atomic="false" (default for plain aria-live): announce only the added or changed nodes. Good for chat logs and activity feeds.
  • aria-relevant (additions, removals, text, all): rarely needed; the defaults are fine.
  • role="log" is a polite region for ordered logs (chat), and role="timer" is for timers (not announced by default).

Loading states

When content loads asynchronously, announce both the start (if it will take a while) and the result.

Search results count

Do not move focus to the results just to announce them. Moving focus is for navigation (a new page, a dialog); announcements are for information.

Alerts

Use role="alert" for urgent messages such as "Connection lost. Changes are not being saved." Keep alerts short, make them dismissible if they persist, and never use them for routine updates; two alerts firing together can cut each other off.

HTML
<div role="alert">Your session expires in 1 minute. <button>Stay signed in</button></div>

Pitfalls

  • Overuse. Announcing every hover, keystroke or animation frame makes pages unusable for screen reader users. Announce only what matters.
  • Live regions inside hidden containers. display: none or hidden removes the region from the accessibility tree; keep the region visible or visually hidden with the .sr-only pattern.
  • Visually hidden is fine. A status region can be invisible on screen if the message is only for screen reader users, but sighted users should have equivalent visible feedback somewhere.
  • Toasts that vanish. If a toast disappears in 3 seconds, some users cannot read it. Give timed messages enough time (at least 5 seconds, or until dismissed) and make sure the same message is also available in context.
  • Testing. Live region support differs between NVDA, JAWS and VoiceOver; test your messages in at least two.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which role is a polite live region?

    role=status implies aria-live=polite and aria-atomic=true. alert is assertive.
  2. 2. Why do you place the empty live region in the HTML at load?

    Assistive technology registers the region first and then watches it for changes.
  3. 3. What does aria-atomic="true" do?

    Atomic regions are announced in full, which keeps a message like 'Cart: 3 items' complete.
  4. 4. A search finishes and results appear below. What is the best way to tell screen reader users?

    A polite status message reports the outcome without stealing focus.

Summary

  • Live regions announce changes without moving focus: role="status" (polite) and role="alert" (assertive).
  • Create the region first, then change its text; keep messages short and meaningful.
  • Use aria-atomic for messages that must be read whole.
  • Avoid overuse, hidden containers and fast-vanishing toasts.

Next: Modals, Dialogs and Popovers