wp.a11y.speak() is a JavaScript method included into WordPress core as off version 4.2.

When content changes dynamically in a web page, wp.a11y.speak() can announce a message using aria-live. Then users who depend on a screen reader will be notified of any change to the content on the page.

Joe Dolson and Andrea Fercia wrote a clear introduction and manual on the method in Let WordPress Speak, new in WordPress 4.2

Example of a wp.a11y.speak() implementation Example of a wp.a11y.speak() implementation

In this example a table with data is displayed. The user can select for example a category and the table with the data below will be updated dynamically.

With wp.a11y.speak() we can announce that the table has been updated with new data.

Note: for wp.a11y.speak() to work best, the screen-reader-text CSS class should be added to your theme CSS. Also, wp.a11y.speak() is only available after DOM ready, so be sure not to call it earlier!

In functions.php In functions.php

add_action( 'wp_enqueue_scripts', 'yourprefix_ajax' );

function yourprefix_ajax() {

    // Register the script.
    wp_register_script( 'your-prefix-ajax', get_template_directory_uri() . '/assets/js/your-ajax-file.js',

    // Localization.
    wp_localize_script( 'your-prefix-ajax', 'yourData', [
        strings' => [
            'resultsFound' => esc_html__( 'New results found and displayed in the table below', 'your-theme' )
    ] );
    wp_enqueue_script( 'your-prefix-ajax' );

Top ↑

In your-ajax-file.js In your-ajax-file.js

Within the js method generating the dynamic changes you can call:

// Announce change of data in the table.
wp.a11y.speak( yourData.strings.resultsFound, 'polite' );

Top ↑

The generated output The generated output

<div id="wp-a11y-speak-polite" aria-live="polite" aria-relevant="additions text" aria-atomic="true" class="screen-reader-text wp-a11y-speak-region">
New results found and displayed in the table below

This <div> will be added to the bottom of the web page.

Top ↑

Resources Resources

  • WordPress speaks with wp.a11y.speak by Sami Keijonen, explanation, examples in GitHub and a demo site
  • Let WordPress Speak, new in WordPress 4.2 by Joe Dolson and Andrea Fercia, introducing and explaining the method
  • The NPM Module @wordpress/a11y that has the “speak” method that allows you to easily announce dynamic interface updates to screen readers using ARIA live regions. This module is inspired by the speak function in wp-a11y.js
  • a11y-speak, a Github repository by Yoast containing a dedicated JS module, called A11ySpeak which makes the wp.a11y.speak functionality more universally available