aria-live-capture

Installation | 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.

Installation

aria-live-capture should be included in development dependencies.

``bash
npm install --save-dev aria-live-capture
`

Usage

Import CaptureAnnouncements from entrypoint.

`ts
import CaptureAnnouncements from 'aria-live-capture';
`

$3

Pass onCapture callback to handle announcements.

| Callback argument | type | value |
| :---------------: | :------: | -------------------------------- |
| announcement | string | Text content of the announcement |
| politenessSetting | string | polite\|assertive |


`ts
CaptureAnnouncements({
onCapture: (announcement, politenessSetting) => {
console.log("${announcement}" was announced with politeness setting "${politenessSetting}");
},
});
`

`
"Loading" was announced with politeness setting "polite"
"Failed to load user details" was announced with politeness setting "assertive"
`

$3

Pass an optional boolean includeShadowDom option to include tracking of live regions in Shadow DOM.
Default value is false.

`ts
CaptureAnnouncements({
includeShadowDom: true,
});
`

$3

The CaptureAnnouncements method returns cleanup function for clearing DOM interceptors.

`ts
const cleanup = CaptureAnnouncements(options);

cleanup();
`

Announcement detection examples

Test online  


`html
Render#1 |


`html
Render#1 |


`html
Render#1 |


`html
Render#1 |

Render#2 |

Loading

PASS ✅ | "Loading" is announced
`


`html
Render#1 |


`html
Render#1 |


`html
Render#1 |


`html
Render#1 |


`html
Render#1 |


`html
Render#1 |


`html
Render#1 |


`html
Render#1 |

With option { includeShadowDom: true }:


`html
Render#1 |

| Feature | Status |
| :-------------: | :----: |
| role | ✅ |
| aria-live | ✅ |
| aria-atomic | ❌ 👷 |
| aria-busy | ❌ |
| aria-relevant` | ❌ |