English
Site menu

live-region-announcements

Live regions should be able to announce status messages

manualWCAG 4.1.3 (AA)confidence: mediumseverity: moderaterobust

Flags a live region hidden from assistive technology or left busy, and, with the live-region hook, one added with its text or shown and filled at once, for manual review.

Applies to. Live regions the page draws: elements whose aria-live is polite or assertive, or, without an aria-live, whose role is status, log or alert, and <output> elements. aria-live="off" turns any of them off. A live region hidden with display: none, visibility: hidden or [hidden] is left out: a region waiting to be shown is the page at rest. A live region behind an open modal <dialog>, which the browser makes inert, is included, though other rules leave that content out. With the live-region hook (liveRegionHookScript), also the live regions it saw given their text in a way that is commonly not announced, whether or not they are still on the page.

Expectation. WCAG 4.1.3: a status message can be presented to the user by assistive technology without receiving focus, which a live region does when its content changes while assistive technology can reach it.

  • A drawn live region inside, or on, aria-hidden="true" or inert, or behind an open modal <dialog>: cantTell (LIVE_REGION_HIDDEN). It is out of the accessibility tree, so nothing it is given can be announced (behind the dialog, while the dialog is open).
  • A live region with aria-busy="true" when the page was scanned: cantTell (LIVE_REGION_BUSY). Assistive technology may hold back its changes until aria-busy is cleared.
  • Recorded by the hook, a live region added to the page with its text already in it, other than role="alert": cantTell (LIVE_REGION_INSERTED_WITH_CONTENT). Screen readers commonly announce changes to a region they already know, not a new region's content.
  • Recorded by the hook, a live region that was hidden and was shown and given its text in the same task: cantTell (LIVE_REGION_SHOWN_AND_FILLED). It was not in the accessibility tree when the text arrived.
  • Otherwise: pass.

Check whether the page uses the region for status messages, and that it is in the page, shown and reachable, before its text changes.

What a finding reports.

  • politeness: the region's, polite or assertive.
  • hiddenBy: for LIVE_REGION_HIDDEN, aria-hidden, inert, or modal for a region behind an open modal <dialog>. A region behind the dialog is modal whatever else hides it (inert or aria-hidden on it or above it, with or without includeHiddenElements): while the dialog is open, it is the cause in effect.
  • text: for the hook's two findings, the text the region was given (up to 300 characters).
  • removed: for the hook's two findings, true when the region was no longer on the page when it was scanned; the occurrence is then on the document element, and region describes it (tag, role, id).

These data.details fields help to read and reproduce a finding. Apart from reasonCode and the few fields Output schema names as stable, they are not a stable contract: a field may be renamed or dropped in a minor release, so don’t build on them.

Examples

pass
<div role="status"></div>

An empty status region, in the page and reachable before any message arrives.

can't tell
<div aria-hidden="true"><div role="status"></div></div>

The region is hidden from assistive technology, so nothing it is given can be announced. A person checks whether the page uses it for status messages.

How to check

When this rule can’t decide, it reports cantTell and leaves the question to a person. Each question it can ask is listed here under its reason code, with the steps to answer it. A finding carries the same steps as howToCheck, in the scan’s language. See Output schema.

LIVE_REGION_BUSY

  1. Find the live region the report names; it had aria-busy="true" when the page was scanned.
  2. Trigger the action that updates the region, then inspect it in the developer tools and see whether aria-busy changes to false or is removed once the update finishes.
  3. Repeat the action with a screen reader running and listen for the message.
  4. If you hear nothing from this region, check whether the page announces the same message another way, for example from another status area that the screen reader reads out. It only counts if you hear the whole message without moving focus.

Pass. The screen reader announces the message without focus moving, because aria-busy is cleared when the update finishes or because the page announces the same message another way.

Fail. aria-busy stays true, the screen reader holds back or skips the message, and the page does not announce it any other way, which fails WCAG 4.1.3.

LIVE_REGION_HIDDEN

  1. Find the live region the report names and note what hides it, as the report says: aria-hidden="true" or inert on it or on an ancestor, or a modal dialog open in front of it.
  2. Check whether a modal dialog was open when the page was scanned; if so, note whether the page writes to the region while it is open, then close it and see whether the region is still hidden.
  3. Trigger the action that updates the region (submit a form, add to cart, run a search) with a screen reader running.
  4. Listen for the message. If you hear nothing, check in the Accessibility pane of the developer tools whether this region, or another status area carrying the same message, is in the tree when the text changes.

Pass. The screen reader announces the message without focus moving, because the region is not hidden when its text changes (or is never used for messages), or because another status area that is not hidden carries the same message.

Fail. The region is still hidden by aria-hidden, inert or an open modal dialog when the message arrives, and nothing else announces it, so the screen reader says nothing, which fails WCAG 4.1.3.

LIVE_REGION_INSERTED_WITH_CONTENT

  1. Find the message the report quotes and the action that shows it (the report gives the text and the region).
  2. Start a screen reader, then perform that action.
  3. Listen for the message without moving focus to it.
  4. If it is not read, check in the developer tools whether the page adds the region already filled; an empty region should be on the page first, with the text written into it later.

Pass. The screen reader announces the message when it appears, without focus moving.

Fail. The message appears on screen but the screen reader does not announce it, because the region was added with its text already in it, which fails WCAG 4.1.3 (ARIA22).

LIVE_REGION_SHOWN_AND_FILLED

  1. Find the message the report quotes and the action that shows it.
  2. Start a screen reader, then perform that action.
  3. Listen for the message without moving focus to it.
  4. If it is not read, check in the developer tools whether the region is hidden until the moment its text is set; it should be visible (or present and empty) before the text arrives.

Pass. The screen reader announces the message when it appears, without focus moving.

Fail. The message appears but the screen reader does not announce it, because the region was shown and filled at the same moment, which fails WCAG 4.1.3 (ARIA22).

View source