aria-live, when and how

aria-live announces dynamic content changes to screen reader users. Using it wrong is worse than not using it. This kata is about learning when it applies, and when it doesn’t.

What aria-live Does

When content inside an aria-live region changes, screen readers announce the new content — even if the user’s focus is somewhere else on the page.

<div aria-live="polite" id="status"></div>

document.getElementById("status").textContent = "Form submitted successfully.";

A screen reader user will hear “Form submitted successfully” when this text appears, without needing to navigate there.

polite vs. assertive

polite — waits for the user to finish their current speech queue before announcing. Right for: status messages, search result counts, save confirmations.

assertive — interrupts whatever the screen reader is saying. Right for: urgent errors that prevent the user from proceeding. Use sparingly.

<!-- Use polite for status updates -->
<div aria-live="polite">3 results found</div>

<!-- Use assertive for blocking errors -->
<div aria-live="assertive">Session expired. Please log in again.</div>

When Not to Use aria-live

If the user triggered the change and focus moves there — announcing the change is redundant. Moving focus to a success message is better than a live region.

For content that updates very frequently — live regions that update continuously (timers, stock tickers) will be unreadable.

For modal dialogs — move focus into the dialog instead. The screen reader reads the dialog context automatically.

Implementation Notes

The live region must exist in the DOM before content is inserted into it. Inserting the region and its content simultaneously is unreliable — some screen readers miss it.

// Correct: region exists, content changes
liveRegion.textContent = "Loading complete";

// Unreliable: inserting region + content together
document.body.insertAdjacentHTML("beforeend", '<div aria-live="polite">Loading complete</div>');

Why It Matters

Screen reader users can’t see visual feedback — spinner animations, toast messages, count updates. aria-live is the mechanism that keeps them informed. Using it correctly is the difference between an accessible app and one that silently leaves users behind.