Live Region

Announces its text to screen readers when the text changes. LiveRegion renders a persistent, visually hidden <span> live region 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.

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.

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".

When not to use

• For status the user must see. Use Alert or Toast, which pair visible UI with their own announcements.
• For hidden text that never changes. Use VisuallyHidden.

1import { Button } from "@ngrok/mantle/button";2import { LiveRegion } from "@ngrok/mantle/live-region";3import { useState } from "react";4 5function ResultsExample() {⋯6	const [count, setCount] = useState(3);7	return (8		<div className="flex flex-col items-start gap-4">⋯9			<Button⋯10				type="button"11				appearance="filled"12				intent="neutral"13				onClick={() => setCount((current) => current + 1)}14			>15				Add a result16			</Button>17			<LiveRegion>{`${count} results found`}</LiveRegion>18			<ul className="list-disc pl-5 text-sm">⋯19				{Array.from({ length: count }, (_, index) => (20					<li key={index}>Result {index + 1}</li>21				))}22			</ul>23		</div>24	);25}

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.

1import { LiveRegion } from "@ngrok/mantle/live-region";2 3<LiveRegion asChild>⋯4	<p>Ready.</p>5</LiveRegion>;

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.

1import { Button } from "@ngrok/mantle/button";2import { LiveRegion } from "@ngrok/mantle/live-region";3import { useState } from "react";4 5function AssertiveExample() {⋯6	const [message, setMessage] = useState("");7	return (8		<div className="flex flex-col items-start gap-4">⋯9			<Button⋯10				type="button"11				appearance="outlined"12				intent="danger"13				onClick={() => setMessage("Session expired. Sign in again.")}14			>15				Expire the session16			</Button>17			<LiveRegion politeness="assertive">{message}</LiveRegion>18			<p className="text-muted text-sm">{message || "The session is active."}</p>19		</div>20	);21}

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.

1import { Button } from "@ngrok/mantle/button";2import { LiveRegion } from "@ngrok/mantle/live-region";3import { useState } from "react";4 5function RouteAnnouncerExample() {⋯6	const [pageName, setPageName] = useState("Dashboard");7	return (8		<div className="flex flex-col items-start gap-4">⋯9			<nav className="flex gap-2">⋯10				<Button⋯11					type="button"12					appearance="outlined"13					intent="neutral"14					onClick={() => setPageName("Dashboard")}15				>16					Dashboard17				</Button>18				<Button⋯19					type="button"20					appearance="outlined"21					intent="neutral"22					onClick={() => setPageName("Settings")}23				>24					Settings25				</Button>26			</nav>27			<LiveRegion>{`Navigated to ${pageName}`}</LiveRegion>28			<h3 className="text-lg font-medium">{pageName}</h3>29		</div>30	);31}

API Reference

LiveRegion

All props from span, plus:

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