Making Your Content Accessible: Adding a "Screen Reader Text" Button to the WordPress Formatting Toolbar

Creating a fully inclusive digital experience means going beyond what meets the eye. While a design may look visually appealing and functional to sighted users, it’s important to remember that those using assistive technology, like screen readers, may face barriers. This is where the concept of visually hidden text comes into play. It connects design with accessibility, ensuring that content which may not be visible to sighted users is still accessible and understandable to assistive technologies.

Consider a client who insists on having a "Read More" link after every post on their site. Repeating the exact same "Read More" text for each link can become redundant for screen readers and fails to provide meaningful context. We don’t recommend this approach. A better solution is to enhance such links with visually hidden text that provides additional context, ensuring assistive technology users receive the necessary details.

By thoughtfully incorporating this text, you can help ensure that all users have equal access to information and context. This practice is particularly important in examples like tables that rely on icons instead of text, sections that need hidden headings to provide semantic context, or forms without explicit visual labels. In essence, when used appropriately, screen reader-friendly text bridges the gap between how sighted users and those with low vision or blindness interact with your digital interfaces, contributing to a fully accessible and inclusive web experience for everyone.

It’s important to use these techniques thoughtfully. Remember that many screen reader users have some level of vision, so what they see and hear should generally align. Screen reader-only content should typically be reserved for information that is visually apparent but may not be clear to blind screen reader users.

This blog post will explore how to effectively implement visually hidden text in WordPress. We'll delve into the existing "screen-reader-text" class, its limitations, and how to overcome them by creating a custom solution for easier application within the WordPress editor.

WordPress's .screen-reader-text class

WordPress core conveniently has a class called .screen-reader-text designed for this purpose. However, this class has some limitations for content editors:

• Limited Application: To apply this class you can use the "Additional CSS Class(es)" field in the block settings. However, this applies a class to the entire block, which may not be ideal if you need to target specific words or phrases.
• Visibility Challenges: Editors cannot easily see the visually hidden text in the editor while editing, potentially leading to content-related issues with hidden text scattered throughout the page.

A custom solution: a screen reader text button

To address these limitations, I created a custom solution: a button in the formatting toolbar that applies visually hidden styles to selected text. 

This solution offers several key advantages:

• Direct Application: Editors can easily apply the visually hidden styles to specific words or phrases within the block.
• Improved Workflow: The ability to see the text while editing ensures that content remains accurate and contextually relevant.
• Increased Accessibility: Empowers editors to directly incorporate accessibility considerations into their content creation process.

By implementing this custom solution, you can significantly enhance the accessibility of your WordPress website while simplifying the content creation process for editors.

How to add the custom button to the formatting toolbar

To create the custom button, we’ll use the Formatting Toolbar API. This allows us to add a button to the toolbar and apply specific formatting to selected text. This guide assumes you have a basic understanding of WordPress plugins and how to load JavaScript within them. If you need a refresher, refer to the Formatting Toolbar API guide for more resources.

Throughout this guide, src/index.js will be referenced as the JavaScript file where changes are implemented. After completing each step, run npm run build to generate build/index.js, which is then loaded onto the post editor screen.

Step 1: Register the new format

The first step is to register the new format, update src/index.js with the following:

import { registerFormatType,toggleFormat } from '@wordpress/rich-text';
import { RichTextToolbarButton } from '@wordpress/block-editor';
import { __ } from '@wordpress/i18n';
registerFormatType( 'my-custom-format/screen-reader-text', {
  title: __( 'Screen Reader Text' ),
  tagName: 'span',
  className: 'screen-reader-text-fe',
  edit: ScreenReaderTextButton,
} );

Step 2: Add the button to the toolbar

Now that we’ve created the format, we can add a button to the toolbar by using the RichTextToolbarButton component. Update src/index.js with the following:

 import { registerFormatType,toggleFormat } from '@wordpress/rich-text';
import { RichTextToolbarButton } from '@wordpress/block-editor';
import { __ } from '@wordpress/i18n';
const ScreenReaderTextButton = ( props ) => {
  const { onChange, value, isActive } = props;
  return (
    <RichTextToolbarButton
      icon="universal-access-alt"
      title={ __( 'Screen Reader Text' ) }
      onClick={ () => {
        onChange(
          toggleFormat( value, {
            type: 'my-custom-format/screen-reader-text',
            attributes: {
              class: 'dashicons-before dashicons-universal-access-alt',
            },
          } ),
        );
      } }
      isActive={ isActive }
    />
  );
};
registerFormatType( 'my-custom-format/screen-reader-text', {
  title: __( 'Screen Reader Text' ),
  tagName: 'span',
  className: 'screen-reader-text-fe',
  edit: ScreenReaderTextButton,
} );

Step 3: Add the styles

Add your frontend styles  for the screen-reader-text-fe class that will be applied. The snippet below will visually hide the text:

src/style.css

.screen-reader-text-fe {
  border: 0;
  height: 1px;
  margin: -1px;
  overflow: hidden;
  padding: 0;
  position: absolute;
  width: 1px;
}

Next, add your editor styles. It’s important for editors to easily view the visually hidden text within the editor while working on the page content. The styles below will override the visually hidden styles used on the frontend, instead displaying the text with a light grey background for clarity.

src/editor.scss

.screen-reader-text-fe,
.screen-reader-text-fe dashicons-before {
	width: auto !important;
	height: auto !important;
	clip: auto !important;
	position: relative !important;
	background-color: #f0f0f0;
}

To confirm it’s working, first build and reload the page. Then, select some text and access the new button by clicking the More button  >  “Screen Reader Text”. Your browser should display the selected text differently from the surrounding content like so:

To better understand how to effectively implement these techniques, let's explore some practical use cases for screen reader text within the WordPress block editor.

Helpful use cases

Tables with icons

A comparison table showing the features of two Slider Plugins. Each feature is marked with a checkmark if available or left blank if not. Visually hidden text can be added to the table cells to ensure screen readers convey the table's information effectively.

Sections with a visually hidden heading

A Recent News section featuring three news cards, preceded by the visually hidden title “Recent News,” which provides context for the card section.

Incorporating visually hidden text into your site is an essential step toward building more accessible web content. Although WordPress includes a built-in "screen-reader-text" class, its limitations can make efficient content creation challenging. By utilizing the Formatting Toolbar API to develop a custom "Screen Reader Text" button, you enable content editors to effortlessly integrate this feature into their workflow.

By embracing these techniques and prioritizing accessibility, you can ensure that your WordPress website is a welcoming and inclusive space for everyone.