# useAnnounce

Returns `announce(message, politeness?)`, which reads a message to screen reader users without moving focus or showing anything on screen. The same message twice is announced twice.

`'polite'` (default) waits until the screen reader is idle; `'assertive'` interrupts it, for errors only. One hidden live region per politeness is shared by all components and removed when the last one unmounts. The function is stable. Nothing runs on the server.

## Import

```ts
import { useAnnounce } from '@vincent.ri/react-tils'
// or only this hook
import { useAnnounce } from '@vincent.ri/react-tils/useAnnounce'
```

## Usage

```ts
const announce = useAnnounce()
const [copy] = useCopyToClipboard()
return <button onClick={async () => (await copy(url)) && announce('Link copied')}>Copy link</button>
```

## When to use it

The result of an action isn't announced by itself: "Copied", "Added to cart", "3 results", "Message sent", "Saved", or a validation error that appears away from focus.

## When not to

Focus moves to the new content (a dialog, an inline error with `aria-describedby`), or the text is in an element that already has `role="status"` or `role="alert"`; screen readers read those anyway.

## API

```ts
function useAnnounce(): (message: string, politeness?: Politeness) => void
```

**Returns** `announce(message, politeness?)`.

### Types

```ts
export type Politeness = "polite" | "assertive";
```

## Browser support

Works in all modern browsers.

## Coming from another library?

Other libraries call this `useAnnouncer`, `useLiveAnnouncer`, `LiveAnnouncer`.

---

346 B minified and brotlied
Source: https://github.com/vincentri/react-tils/blob/main/src/useAnnounce.ts
Docs page: https://vincentri.github.io/react-tils/hooks/useAnnounce/
Previous: [useControllableState](https://vincentri.github.io/react-tils/hooks/useControllableState.md)
Next: [usePrevious](https://vincentri.github.io/react-tils/hooks/usePrevious.md)