useAnnouncer

Pro

Announces a message to screen-reader users from app code: const announce = useAnnouncer(); announce("Saved"), or announce("Connection lost", "assertive") for something that can't wait. The same words announced twice are spoken twice, which a live region of your own that is given the same text again doesn't do. An announcement is cleared from the page a few seconds after it is made, so a screen reader reading the page later doesn't find stale words.

Every component that uses the hook shares one visually hidden live region per politeness, put in document.body when the first of them mounts, so the region is there before the first message (a region added with its text is often not read), and taken away when the last unmounts. The text is plain text, never HTML, with bidi controls marked by neutralizeBidi, so text from a model or a tool can be announced as it is. An announcement made while no component using the hook is mounted, or on the server, does nothing.

Markdown

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0, 2.5.0, 2.5.1, 2.6.0, 2.6.1, 2.6.2, 2.7.0, 2.8.0, 2.9.0, 2.10.0, 3.0.0, 4.0.0, 4.0.1, 4.0.2 and 4.1.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/use-announcer

Brings in: bidi, tokens

Usage

TSX · The example above

"use client"

import * as React from "react"
import { Button } from "@/components/candor/ui/button"
import { useAnnouncer } from "@/lib/candor/use-announcer"

export default function Example() {
  const announce = useAnnouncer()
  const [saves, setSaves] = React.useState(0)
  return (
    <div className="flex flex-col items-start gap-2">
      <Button
        variant="outline"
        size="sm"
        onClick={() => {
          setSaves((n) => n + 1)
          // Said again on every press, though the words are the same.
          announce("Draft saved")
        }}
      >
        Save draft
      </Button>
      <p className="text-xs text-muted-foreground">Saved {saves} times. A screen reader hears “Draft saved” each time.</p>
    </div>
  )
}

Functions

useAnnouncer()