Messages Announcer

Announce content changes.

It is common on single-page web apps that assistive technologies completely ignore significant changes happening inside a page, mainly because we manipulate the DOM with JavasScript.

Like the RouteAnnouncer, with the MessagesAnnoucer, we create an ARIA live region that the assistive technologies will monitor. So, any changes that you push to this component, a screen-reader will announce them.

Credit Card Form

Card Number

Card Holder's Name

Expiration DateMonth01 - January02 - February03 - March04 - April05 - May06 - June07 - July08 - August09 - September10 - October11 - November12 - DecemberYear2021202220232024202520262027202820292030203120322033

CVV

How to

• Start your screen-reader (like VoiceOver or Narrator)
• Focus on the "Pay" button.
• Notice that a message will be displayed.
• However, the screen-reader will output a different and more meaningful message.

Usage

You can use component to wrap the contents of a form, for instance. This renders the form and, alongside it, the ARIA live region.

import { MessagesAnnouncer } from "@feedzai/react-a11y-tools";
...
return (
	<MessagesAnnouncer>
		<form onSubmit={handleOnSubmit}>
			...
		</form>
	</MessagesAnnouncer>
);

useMessageAnnouncer

To dispatch messages inside a functional component, you can take advantage of the useMessageAnnouncer custom hook.

First, import the hook at the top of the file:

import { useMessageAnnouncer } from "@feedzai/react-a11y-tools";

Then, after you've defined your component, save the hook to a constant:

function YourComponent(props) {
	const setMessage = useMessageAnnouncer();

Finally, use the function whenever you'd like to announce something.

function onClick() {
	setMessage({
		message: "The user has performed an action that it will be announced!",
		politeness: "assertive",
	});
}

return (
	<button type="button" onClick={onClick}>
		Send Message
	</button>
);

Global State

The component takes advantage of React's Context API to use the updater function anywhere inside the MessagesAnnouncer children. To have the announcer available for the whole app, consider wrapping the content with it. This way, you can access the setMessage function from any component inside.

import { MessagesAnnouncer } from "@feedzai/react-a11y-tools";
...
return (
	<MessagesAnnouncer>
		<YourComponent />
	</MessagesAnnouncer>
);

Working alongside Route Announcer

You can use the MessageAnnouncer along with the RouteAnnouncer. However, we recommend that you still place the RouteAnnouncer at the top and then inside it, the MessagesAnnouncer.

import { MessagesAnnouncer } from "@feedzai/react-a11y-tools";
...
return (
	<RouteAnnouncer pathname={pathname}>
		<MessagesAnnouncer>
			<YourComponent />
		</MessagesAnnouncer>
	</RouteAnnouncer>
);