Skip to main content
Beta: Front-End Checklist is currently in beta. Some issues are still being fixed. Thanks for your patience.

Announce dynamic content with ARIA live regions

Dynamic content updates are announced to screen readers using appropriate ARIA live regions.

Utilities
Quick take
Typical fix time 20 min
  • Use aria-live='polite' for non-urgent updates (cart count, status messages)
  • Use aria-live='assertive' only for critical alerts (errors, session expiry)
  • Use role='alert' or role='status' for semantic live regions
  • The live region must exist in DOM before content changes
Why it matters: Without live regions, screen reader users miss dynamic updates entirely—they won't know their form submitted, their cart updated, or an error occurred.

Rule Details

ARIA live regions announce dynamic content changes to screen readers without requiring focus to move.

Code Example

<!-- Polite: Announced after current speech finishes -->
<div aria-live="polite" id="status">
  <!-- Content inserted here will be announced -->
</div>
 
<!-- Assertive: Interrupts current speech immediately -->
<div aria-live="assertive" id="error">
  <!-- Critical messages only -->
</div>

Why It Matters

Without live regions, screen reader users miss dynamic updates entirely—they won't know their form submitted, their cart updated, or an error occurred.

Politeness Levels

LevelUse ForExample
politeNon-urgent updatesCart count, search results
assertiveCritical alertsErrors, session expiry
offDisable announcementsFrequently updating content

Semantic Live Regions

<!-- role="alert" implies aria-live="assertive" -->
<div role="alert">
  Your session will expire in 2 minutes
</div>
 
<!-- role="status" implies aria-live="polite" -->
<div role="status">
  3 items added to cart
</div>

Common Use Cases

Form Validation Errors

function FormField({ label, error }) {
  const errorId = `${label}-error`
 
  return (
    <div>
      <label>{label}</label>
      <input aria-describedby={error ? errorId : undefined} />
      {/* Live region for errors */}
      <div role="alert" id={errorId}>
        {error}
      </div>
    </div>
  )
}

Loading States

function SearchResults({ isLoading, results }) {
  return (
    <div>
      {/* Status announcements */}
      <div role="status" aria-live="polite">
        {isLoading && 'Loading results...'}
        {!isLoading && `${results.length} results found`}
      </div>
 
      <ul>
        {results.map(item => <li key={item.id}>{item.name}</li>)}
      </ul>
    </div>
  )
}

Toast Notifications

function Toast({ message, type }) {
  return (
    <div
      role={type === 'error' ? 'alert' : 'status'}
      aria-live={type === 'error' ? 'assertive' : 'polite'}
      className="toast"
    >
      {message}
    </div>
  )
}

Cart Updates

function CartIcon({ count }) {
  return (
    <div>
      <button aria-label={`Cart, ${count} items`}>
        <ShoppingCartIcon />
        <span>{count}</span>
      </button>
      {/* Announce changes */}
      <div role="status" className="sr-only">
        {count} items in cart
      </div>
    </div>
  )
}

Important Rules

<!-- ❌ Bad: Live region added with content -->
<div aria-live="polite">New message!</div>
 
<!-- ✅ Good: Live region exists, content added later -->
<div aria-live="polite" id="messages"></div>
<script>
  // Content change triggers announcement
  document.getElementById('messages').textContent = 'New message!'
</script>

Exceptions

  • Prefer native HTML semantics over ARIA when both are possible; some apparent ARIA failures disappear when the underlying element is corrected.
  • A missing ARIA attribute is not automatically the strongest finding if the control is already semantically broken, unnamed, or keyboard-inaccessible.
  • Do not add ARIA only to satisfy the rule if the feature should instead be implemented with a native element or a simpler interaction pattern.

Verification

Automated Checks

  • Use browser accessibility tooling, axe, Lighthouse, or equivalent automated checks against a representative rendered state.

Manual Checks

  • Enable screen reader (NVDA, VoiceOver)
  • Trigger dynamic content updates
  • Verify announcements occur at appropriate times
  • Check that assertive regions don't interrupt unnecessarily

Use with AI

Copy these prompts to use with your AI assistant, or install the MCP server to use directly from Claude, Cursor, or Windsurf.

Check

Verify implementation

Verify that dynamic content changes (notifications, form errors, loading states) use aria-live regions appropriately.

Fix

Auto-fix issues

Add aria-live attributes with correct politeness levels (polite, assertive) to containers with dynamic content.

Explain

Learn more

Explain how ARIA live regions enable screen readers to announce content changes without requiring user focus.

Review

Code review

Review the rendered markup and interactive states that affect Announce dynamic content with ARIA live regions. Flag exact elements, roles, labels, focus behavior, or keyboard interactions that violate the rule, and note how to verify the fix with browser accessibility tooling or assistive tech.

Sources

References used to support the guidance in this rule.

Further Reading

Tools and supplementary material for exploring the topic in more depth.

axe DevTools
deque.comTool

Rules that often go hand-in-hand with this one.

Ensure ARIA attributes are valid

All ARIA attributes must be valid and exist in the WAI-ARIA specification.

Accessibility
Ensure ARIA roles contain required child roles

Elements with certain ARIA roles must contain the required child roles or the widget structure will be broken for assistive technologies.

Accessibility
Provide accessible names for tree items

All elements with role="treeitem" must have a descriptive accessible name so screen reader users can navigate hierarchical tree widgets.

Accessibility
Hide decorative elements from assistive technology

Decorative images and visual elements are hidden from screen readers using aria-hidden or empty alt attributes.

Accessibility

Was this rule helpful?

Your feedback helps improve rule quality. This stays internal for now.

Loading feedback...
0 / 385