Skip to main content

Live Region

A persistent, visually hidden region that announces its text to screen readers when the text changes. Keep LiveRegion mounted from first paint and swap only its children.

When to use

  • Announce a completed client-side navigation: the new page name, after a route change.
  • Announce an async result that moves focus nowhere: "3 results found", "Draft saved".
  • Prefer Toast for status the user must see. It announces its message.
  • Prefer Alert for a message that stays visible in the page. It announces only when you pass it a role.
  • Prefer VisuallyHidden for hidden text that never changes.

Polymorphism

LiveRegion accepts an asChild prop. When true, it renders its single child instead of its default <span>, forwarding its class names, ARIA attributes, data-* attributes, and ref onto that child.

Announcing reliably

A live region announces reliably only when it already exists in the accessibility tree before its text changes. Keep LiveRegion mounted from first paint and swap only its children.

A screen reader does not re-announce a message identical to the previous one. When the same message must repeat, clear the children first.

Politeness

politeness defaults to "polite": the announcement waits for the screen reader's current utterance to finish. Pass "assertive" only when a delayed announcement would mislead the user (a session about to expire, a failed save). An assertive region interrupts the screen reader's current utterance.

By default, LiveRegion renders a persistent, visually hidden <span> with role="status" and aria-live="polite". The redundant aria-live covers screen reader and browser pairs that honor only one of the two. When politeness is "assertive", it renders role="alert" alone. The role already carries assertive live-region semantics, and a redundant aria-live makes VoiceOver on iOS announce the message twice.

Announcing route changes

A single-page app repaints on navigation without a page load, so screen readers announce nothing. Feed a persistent LiveRegion the page name from your router's location, so it announces each completed navigation. The demo swaps pages with local state because the docs site cannot navigate inside an example. In your app, derive pageName from the router's location instead. The Route Announcer recipe is the complete pattern wired to React Router: page-name fallbacks, repeat-message handling, and tests.

API Reference

LiveRegion

All props from span, plus:

PropTypeDefaultDescription
asChild?booleanfalseUse the asChild prop to compose the LiveRegion behavior onto alternative element types or your own React components.
children?ReactNodeThe message to announce. Screen readers announce it each time it changes; keep the region mounted and swap only this.
className?stringAdditional CSS classes to apply to the region.
politeness?"polite" | "assertive""polite"How urgently a screen reader announces a changed message: "polite" waits for the current utterance to finish, "assertive" interrupts it. Also derives role: "status" or "alert".

The derived role and aria-live read as defaults: a role or aria-live prop wins. aria-atomic defaults to "true" so the region re-reads the whole message, not the changed characters.

Data attributes

Data AttributeValueDescription
data-slot"live-region"Stamped on the rendered element, and joined onto the child via asChild.