https://github.com/seanwuapps/sr-speak
sr-speak provides utilities that utilises ARIA live regions to help screen reader users hear updates happened on the page.
https://github.com/seanwuapps/sr-speak
a11y announcement aria live-regions screen-reader
Last synced: about 1 month ago
JSON representation
sr-speak provides utilities that utilises ARIA live regions to help screen reader users hear updates happened on the page.
- Host: GitHub
- URL: https://github.com/seanwuapps/sr-speak
- Owner: seanwuapps
- License: mit
- Created: 2024-10-12T08:06:23.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-13T11:16:13.000Z (over 1 year ago)
- Last Synced: 2026-01-13T10:42:19.048Z (about 2 months ago)
- Topics: a11y, announcement, aria, live-regions, screen-reader
- Language: TypeScript
- Homepage:
- Size: 12.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# 📢 SR Speak
`sr-speak` provides utilities that utilises ARIA live regions to help screen reader users hear updates happened on the page.
## Install
```bash
npm install sr-speak
```
## Setup "speaker"
Aria live regions need to be inside the DOM for Screen Readers to accurately monitor changes to its content.
```js
import { setupSpeaker } from "sr-speak";
// call setupSpeak on page load
setupSpeaker();
```
You only need to do this once per page load, in the case of a SPA app, call this once in your app initialisation.
## Speak
```js
import { speak } from "sr-speak";
// ...
// (e.g. when user clicks Search button)
speak("Searching..."); // default politeness is 'polite'
// (e.g. error occurred)
speak("You shall not pass", "assertive");
```
## Under the hood and Politeness
When `setupSpeaker` is called, 2 visually hidden elements are created and appended to the body element. These 2 elements are the live regions, one for `polite` messages and the other one for `assertive` messages.
by default, when you call the `speak` function, the `aria-live="polite"` content is updated, you can choose to update the `aria-live="assertive"` live region by specifying the politeness in the second parameter. e.g. `speak('Important message', 'assertive')`
[Read more about live regions in MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions#live_regions)