Installation

pnpm dlx uselab@latest add use-a11y-announcer

Usage

import * as React from "react"
 
import { useA11yAnnouncer } from "@/hooks/use-a11y-announcer"
 
export function Component() {
  const { announce } = useA11yAnnouncer()
  const [message, setMessage] = React.useState("Form submitted successfully")
 
  return (
    <div>
      <input
        value={message}
        onChange={(e) => setMessage(e.target.value)}
        aria-label="Announcement text"
      />
      <button onClick={() => announce(message, "polite")}>
        Announce (polite)
      </button>
      <button onClick={() => announce(message, "assertive")}>
        Announce (assertive)
      </button>
    </div>
  )
}

Key Points

1. useA11yAnnouncer():

   • Creates shared ARIA live regions (polite and assertive) appended to document.body.
   • Returns announce(text, politeness) to announce messages for screen readers.
   • Politeness defaults to "polite". Use "assertive" for urgent messages.

2. Behavior:

   • Uses visually hidden live regions; calling announce briefly clears then sets text to ensure it is read.
   • Safe for multiple calls; the hook reuses the same polite/assertive nodes.

API Reference

Return Values

Use Cases

• Announce form submission success/fail messages.
• Screen reader cues for navigation changes (e.g., tab changes, modal open/close).
• Status updates for background tasks or live validations.