Feedback on dynamic changes

Using ARIA Live in WordPress

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

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: wp.a11y.speak() is only available after DOM ready, so be sure not to call it earlier!

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',
        array(
            'wp-a11y',
        ),
        false,
        true
    );

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

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' );

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
</div>

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

Using the npm package

The wp.a11y.speak() functionality is also available from the NPM package @wordpress/a11y.

Install the module:

npm install @wordpress/a11y --save

Example usage:

import { speak } from '@wordpress/a11y';

// For polite messages that shouldn't interrupt what screen readers are currently announcing.
speak( 'The message you want to send to the ARIA live region' );

// For assertive messages that should interrupt what screen readers are currently announcing.
speak( 'The message you want to send to the ARIA live region', 'assertive' );

Resources

Other resources

  • First published: October 10, 2025
  • Last updated: August 10, 2026
  • Edit article: Improve it on GitHub

Other pages in: Frontend code

  • Accessible name

    Give an (interactive) HTML element the correct accessible name.

  • Semantic HTML

    Learn why using semantic HTML is essential for web accessibility.

  • Handling focus

    Make the keyboard focus visible, predictable, and meaningful.

  • Heading structure

    How to use headings in theme development in an accessible way.

  • Images

    What is important to for developers when they implement images in a theme, plugin or in WordPress core.

  • Landmarks

    Learn what ARIA landmarks are and how to use them.

  • Pattern libraries

    Libraries with accessible patterns for web components.

  • Tables in code

    Tables in theme and plugin development

  • CSS screen-reader-text

    Learn about the CSS class screen-reader-text and how to use it.

  • Components

    Recommendations and set up of web components for WordPress.

Back to: Frontend code

Quick links and main topics

Quick links

Content

Disclaimer: This documentation is intended to help the WordPress community understand and implement accessible practices. It is not a replacement for the official Web Content Accessibility Guidelines. Please read the full disclaimer.

Back to top