WordPress speaks with wp.a11y.speak

I know I’m really late in the game but WordPress can speak! And has been speaking since version 4.2. Lately I’ve been learning more Javascript and needed this feature in one project. In this article I’ll try to explain simplified version how WordPress speaks with wp.a11y.speak() JavaScript method.

Usually we have spinner or animation to indicate that our AJAX update have happened, and we can see the end result. With wp.a11y.speak() assistive technologies like screen readers can announce same updates from AJAX responses. Isn’t that cool!

Here are reference article and demo links:

How WordPress speaks

In my demo I have two examples:

  1. Filter contacts based on the city where they live.
  2. Filter posts by category using WordPress REST API.

As you can see from the demo site both forms have select HTML element but there is no submit button at all. We do dynamic changes using Javascript every time option have been changed. That’s where wp.a11y.speak() kicks in.

When you enqueue wp-a11y two empty placeholders are added just before closing body element. HTML code looks like this.

ARIA polite:

<div id="wp-a11y-speak-polite" class="screen-reader-text wp-a11y-speak-region" aria-live="polite" aria-relevant="additions text" aria-atomic="true"></div>

ARIA assertive:

<div id="wp-a11y-speak-assertive" class="screen-reader-text wp-a11y-speak-region" aria-live="assertive" aria-relevant="additions text" aria-atomic="true"></div>

Now you can call wp.a11y.speak( UpdateMessage ) method two ways in your Javascript:

  1. Calling wp.a11y.speak( 'Update successful message', 'polite' ) notify updates but wait before other tasks are done by assistive technologies. This is the default value.
  2. Calling wp.a11y.speak( 'Update successful message', 'assertive' ) notify updates immediately.

For example wp.a11y.speak( 'Update successful message', 'polite' ) updates message inside the div element and screen readers announce the update.

<div id="wp-a11y-speak-polite" class="screen-reader-text wp-a11y-speak-region" aria-live="polite" aria-relevant="additions text" aria-atomic="true">Update successful message</div>

In VoiceOver it looks like this after filtering value have changed:

Announce update message in VoiceOver

Video demo

Video might help undestand better how VoiceOver announce updates.

Reference links

That’s it. Pretty cool if you ask me. Here are reference article and demo links one more time: