AriaLiveAnnouncer

AriaLiveAnnouncer and useAnnounce read dynamic announcements to screen reader users.

AriaLiveAnnouncer renders two hidden live regions (polite and assertive); add it once at the app root. useAnnounce() returns { announce }, called as announce(message, { politeness, batchId }). Announcements are queued, and batchId collapses a burst of announcements into the latest one. Without the provider, useAnnounce creates its own live regions in <body>.

Turn on a screen reader (Narrator: Ctrl + Win + Enter) to hear it.

Import

Install from npm, copy the source into your project with @yugen-ui/cli or the shadcn CLI, or import directly when working in this repo.

TSX

// npm install yugen-uiimport { AriaLiveAnnouncer, useAnnounce } from "yugen-ui";

Variants

Each tile is a standalone example: hover to copy, or press Code to see the source.

Provider at the root

Wrap the app in AriaLiveAnnouncer; any child component can then use useAnnounce.

10 results: Apple, Banana, Orange, Mango, Pineapple, Grape, Guava, Plum, Kiwi, Pear

batchId: merging repeated announcements

Type quickly in the search box: only the latest result count is read.

Usage

Use polite for ordinary feedback (saved, result count); use assertive only for urgent errors.
Keep announcements short and clear when heard on their own.
Use batchId for events that repeat quickly (typing, dragging a slider).

Don't

Don't announce every small change in the UI.
Don't use announcements instead of visible content. Sighted users need the feedback too.

Props

Prop · Type	Default	Description
AriaLiveAnnouncer.childrenReactNode	Default: —	The app tree; rendered together with the two hidden live regions.
useAnnounce()() => { announce }	Default: —	Returns the announce function (falls back to a live region in <body> when there is no provider).
announce(message, options?)(string, AnnounceOptions) => void	Default: —	Adds an announcement to the queue.
options.politeness"polite" \| "assertive"	Default: "polite"	Reading priority.
options.batchIdstring	Default: —	A queued announcement with the same batchId is replaced by the new one.