@curi/side-effect-aria-live

Installation

The package can be installed through npm (you need to have Node & NPM installed).

npm install @curi/side-effect-aria-live

Prefer inline scripts? A full (.umd.js) and minified (.min.js) script is available for every version through Unpkg. You can access the package's exports through window.CuriSideEffectAriaLive.

About

When you navigate in a non-single-page application, users who rely on a screen reader will get an announcement about the navigation. Unfortunately, this behavior does not natively exist with single-page applications and the History API.

This side-effect usea ARIA live regions to announce navigations to users who use screen readers.

API

ariaLiveEffect

When you create an ARIA live side effect, an element with a aria-live attribute will be added to the DOM. This element will be styled to not be displayed on screen (but not actually hidden) so that only screen readers detect it.

Warning: This side-effect should only be used in the browser.

The side-effect factory takes a function, which will receives the same arguments as an observer (response, navigation, and router). Using the objects, the function returns a string, which is the message about the navigation that will be read by the screen reader.

The DOM element's aria-live attribute will be "assertive" by default, but you can use the side-effect factory's second argument to pass an alternative (i.e. >"polite").

import { curi } from '@curi/router';
import ariaLive from '@curi/side-effect-aria-live';

const announcer = ariaLive(
  ({ response }) => `Navigated to ${response.title}`
);

const politeAnnouncer = ariaLive(
  ({ response }) => `Navigated to ${response.title}`,
  "polite"
);

const router = curi(history, routes, {
  sideEffects: [announcer]
});