Title: @wordpress/a11y Published: March 9, 2021 Last modified: October 8, 2026 --- # @wordpress/a11y ## In this article * [Installation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#installation) * [API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#api) - [setup](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#setup) - [speak](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#speak) - [Background](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#background) * [Browser support](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#browser-support) * [Contributing to this package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#contributing-to-this-package) [ Back to top](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#wp--skip-link--target) Accessibility utilities for WordPress. ## 󠀁[Installation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#installation)󠁿 Install the module ```bash npm install @wordpress/a11y --save ``` _This package assumes that your code will run in an **ES2015+** environment. If you’re using an environment that has limited or no support for such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._ ## 󠀁[API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#api)󠁿 ### 󠀁[setup](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#setup)󠁿 Create the live regions. ### 󠀁[speak](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#speak)󠁿 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`. _Usage_ ```javascript 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' ); ``` _Parameters_ * _message_ `string`: The message to be announced by assistive technologies. * _ariaLive_ `['polite' | 'assertive']`: The politeness level for aria-live; default:‘ polite’. ### 󠀁[Background](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#background)󠁿 For context I’ll quote [this article on WordPress.org](https://make.wordpress.org/accessibility/2015/04/15/let-wordpress-speak-new-in-wordpress-4-2/) by [@joedolson](https://github.com/joedolson): > > #### 󠀁[Why.](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#why)󠁿 > > In modern web development, updating discrete regions of a screen with JavaScript > is common. The use of AJAX responses in modern JavaScript-based User Interfaces > allows web developers to create beautiful interfaces similar to Desktop applications > that don’t require pages to reload or refresh. > JavaScript can create great usability improvements for most users – but when > content is updated dynamically, it has the potential to introduce accessibility > issues. This is one of the steps you can take to handle that problem. > > #### 󠀁[What.](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#what)󠁿 > > When a portion of a page is updated with JavaScript, the update is usually highlighted > with animation and bright colors, and is easy to see. But if you don’t have the > ability to see the screen, you don’t know this has happened, unless the updated > region is marked as an ARIA-live region. > If this isn’t marked, there’s no notification for screen readers. But it’s also > possible that all the region content will be announced after an update, if the > ARIA live region is too large. You want to provide users with just a simple, concise > message. > > #### 󠀁[How.](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#how)󠁿 > > That’s what `wp.a11y.speak()` is meant for. It’s a simple tool that creates and > appends an ARIA live notifications area to the element where developers can dispatch > text messages. Assistive technologies will automatically announce any text change > in this area. This ARIA live region has an ARIA role of “status” so it has an > implicit aria-live value of polite and an implicit aria-atomic value of true. > This means assistive technologies will notify users of updates but generally > do not interrupt the current task, and updates take low priority. If you’re creating > an application with higher priority updates (such as a notification that their > current session is about to expire, for example), then you’ll want to create your > own method with an aria-live value of assertive. ## 󠀁[Browser support](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#browser-support)󠁿 See [https://make.wordpress.org/core/handbook/best-practices/browser-support/](https://make.wordpress.org/core/handbook/best-practices/browser-support/) ## 󠀁[Contributing to this package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-a11y/?output_format=md#contributing-to-this-package)󠁿 This is an individual package that’s part of the Gutenberg project. The project is organized as a monorepo. It’s made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects. To find out more about contributing to this package or Gutenberg as a whole, please read the project’s main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md). First published March 9, 2021 Last updated October 8, 2026 Edit article [ Improve it on GitHub: @wordpress/a11y ](https://github.com/WordPress/gutenberg/edit/trunk/packages/a11y/README.md) [ Previous: @wordpress/library-export-default-webpack-plugin](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-library-export-default-webpack-plugin/) [ Next: @wordpress/abilities](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-abilities/)