Capture announcements of ARIA-live regions
npm install aria-live-captureInstallation | Usage | Announcement detection examples | Support
> Capture announcements of ARIA live regions.
aria-live-capture is an utility tool for inspecting announcements of ARIA live regions.
When developing an application which utilizes ARIA live announcements it is often frustrating to toggle screen readers and other assistive technologies constantly on/off during development.
This tool aims to help developers easily see announcements without having to use actual screen readers.
However final assertion should always be made with the actual target assistive technology.
For online demo see Storybook playground.
For validating ARIA live regions in tests see extend-to-be-announced.
For Storybook integration see storybook-addon-aria-live.
Read more about inspiration from Building testing tools for ARIA live regions.
aria-live-capture should be included in development dependencies.
``bash`
npm install --save-dev aria-live-capture
Import CaptureAnnouncements from entrypoint.
`ts`
import CaptureAnnouncements from 'aria-live-capture';
Pass onCapture callback to handle announcements.
| Callback argument | type | value |
| :---------------: | :------: | -------------------------------- |
| announcement | string | Text content of the announcement |string
| politenessSetting | | polite\|assertive |
`ts"${announcement}" was announced with politeness setting "${politenessSetting}"
CaptureAnnouncements({
onCapture: (announcement, politenessSetting) => {
console.log();`
},
});
``
"Loading" was announced with politeness setting "polite"
"Failed to load user details" was announced with politeness setting "assertive"
Pass an optional boolean includeShadowDom option to include tracking of live regions in Shadow DOM.false
Default value is .
`ts`
CaptureAnnouncements({
includeShadowDom: true,
});
The CaptureAnnouncements method returns cleanup function for clearing DOM interceptors.
`ts
const cleanup = CaptureAnnouncements(options);
cleanup();
`
`html`
Render#1 |
Render#2 | Loading
PASS ✅ | "Loading" is announced
`html`
Render#1 |
Render#2 | Loading
PASS ✅ | "Loading" is announced
`html`
Render#1 |
Render#2 | Loading
PASS ✅ | "Loading" is announced
`html`
Render#1 |
Render#2 |
PASS ✅ | "Loading" is announced
`html`
Render#1 | Loading
FAIL ❌ | "Loading" is not announced
`html`
Render#1 |
Render#2 | Loading
FAIL ❌ | "Loading" is not announced
`html`
Render#1 |
Render#2 | Loading
FAIL ❌ | "Loading" is not announced
`html`
Render#1 | Error
PASS ✅ | "Error" is announced
`html`
Render#1 | Error
FAIL ❌ | "Error" is not announced
`html`
Render#1 |
Render#2 | Error
PASS ✅ | "Error" is announced
`html`
Render#1 |
|
|
|
Render#2 |
| Loading
|
|
PASS ✅ | "Loading" is announced
`html`
Render#1 |
Render#2 | Loading
FAIL ❌ | "Loading" is not announced
With option { includeShadowDom: true }:
`html`
Render#1 |
| #shadow-root
|
|
|
Render#2 |
| #shadow-root
| Loading
|
|
PASS ✅ | "Loading" is announced
| Feature | Status |
| :-------------: | :----: |
| role | ✅ |aria-live
| | ✅ |aria-atomic
| | ❌ 👷 |aria-busy
| | ❌ |aria-relevant` | ❌ |
|