Usage
Imperatively announces a message to screen readers through a visually-hidden live region. Use it for state that is only conveyed visually; search result counts, "no results", loading and saved confirmations, validation errors (WCAG 4.1.3 Status Messages). The polite and assertive regions are created empty on first use and stay mounted, which is what makes announcements reliable: most screen readers ignore a live region that is inserted together with its content. Each message is cleared a couple of seconds after it is announced so stale status does not linger in the accessibility tree.
ts
Best practices
| Guidance | Practices |
|---|---|
| Do | Reach for this instead of hand-rolling an aria-live div; a region rendered with its content usually does not announce at all. |
| Do | Keep "polite" for status and result counts; reserve "assertive" for errors and time-sensitive alerts, since it interrupts whatever the screen reader is saying. |
| Do | Announce the outcome, not the interaction; "12 results" rather than "search ran". |
| Don't | Announce content that is already visible and correctly labeled in the DOM; that doubles up for screen reader users. |
Returns
| Field | Type | Description |
|---|---|---|
| announce | (message: string, politeness?: "polite" | "assertive") => void | Speaks a message through the shared live region. Politeness defaults to "polite"; an empty message clears any lingering status instead of announcing. |