# Status messages are announced via aria-live

- **Pattern:** `ab-000127` (`accessibility-wcag.understandable.aria-live`)
- **Severity:** low
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000127
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000127)

## Why it matters

Toast notifications, form submission confirmations, live search result counts, and loading states are invisible to screen reader users unless explicitly marked with `aria-live`. WCAG 2.2 SC 4.1.3 (Status Messages) is a Level AA requirement added in WCAG 2.1: status messages must be programmatically determinable through role or property so they can be announced without receiving focus. A 'Form saved successfully' toast that a sighted user sees and a screen reader user never hears is a silent UX failure.

## Severity rationale

Low because the omission silences feedback without blocking the underlying action — users can still submit forms and navigate — but violating WCAG 2.2 SC 4.1.3 at Level AA means screen reader users never know whether their actions succeeded.

## Remediation

Wrap non-intrusive status messages in an `aria-live="polite"` region so screen readers announce them after completing the current task. Use `role="alert"` for urgent errors.

```tsx
// Polite announcement — waits for current speech to finish
<div aria-live="polite" aria-atomic="true" className="sr-only">
  {statusMessage}
</div>

// Alert — interrupts current speech immediately
{criticalError && (
  <div role="alert" className="text-red-600">
    {criticalError}
  </div>
)}

// Toast pattern — rendered in portal, still announced
export function Toast({ message }: { message: string }) {
  return createPortal(
    <div role="status" aria-live="polite" className="toast">
      {message}
    </div>,
    document.body
  )
}
```

Ensure the `aria-live` region exists in the DOM before any message is inserted — toggling both the region and its content simultaneously can prevent announcements in some screen readers.

## Detection

- **ID:** `aria-live`
- **Severity:** `low`
- **What to look for:** Enumerate every relevant item. Look for status messages, notifications, alerts, loading indicators, and toast messages. Check for `aria-live="polite"` or `role="alert"` (which implies `aria-live="assertive"`).
- **Pass criteria:** At least 1 of the following conditions is met. Status messages are announced to screen readers via `aria-live="polite"`, `role="alert"`, or `aria-live="assertive"`. Messages do not move focus.
- **Fail criteria:** Status messages are rendered but not announced to screen readers.
- **Skip (N/A) when:** The project has no dynamic status messages.
- **Detail on fail:** Example: `"Toast notification shows 'Form saved successfully' but has no aria-live attribute. Screen readers do not announce the message"`
- **Remediation:** Add aria-live to status messages:

  ```tsx
  <div aria-live="polite" aria-atomic="true">
    {message && <p>{message}</p>}
  </div>

  {/* Or use role="alert" for urgent messages */}
  {error && (
    <div role="alert">
      <p>{error}</p>
    </div>
  )}
  ```

---

## External references

- wcag 4.1.3
- section-508 502.3.14

Taxons: accessibility

HTML version: https://auditbuffet.com/patterns/ab-000127