Using an accessibility-ready theme helps ensure your site is accessible but anyone that adds, edits, or publishes content on your site can quickly make the site less accessible.

The Accessible Content plugin is designed to check your pages and posts for potential accessibility issues and highlight any content that needs attention.

Refer to the Complete Guide To WordPress Accessibility to learn more about accessibility.

Review Accessibility issues

Once you have activated the Accessible Content plugin in Plugins > All you check the post or page in preview.

Preview post

Any potential accessibility issues are highlighted with an underline. The highlighted error, is always accompanied by an error messages at the bottom of the page, outlining what went wrong and how it can be improved.

Highlighted accessibility issues

Use Next Issue and Previous Issue to review each issue then edit and update the post/page to fix the issue(s).

Edit the content to fix the issues

Finally preview the changes to confirm the issues have been addressed.

In this example, the heading 4 was changed to a heading 2 and the alt text was added to the image. The two issues left are the link opens in a new tab and is linking to a PDF.

Issues fixed

Below is information on how accessible content plugin assesses issues and how to fix the issues:

Alt Tags on Images

Adding Alt text (alternative text) to images is important for screen reader users with visual impairments. It helps to provide context by summarizing the purpose of the image on the page.

Learn more about Alt Tags on images and how to add alt tags in Chapter 4 of the Complete Guide To WordPress Accessibility.

Frontend Replacement Alt Tags

Enabling frontend replacement in Settings > Accessibility adds fallback Alt tags for all the images that have them.

Front end replacement

This processes the images added to content before the plugin was active, as well as making changes to images in Media > Alt Text.

makes changes to images in media > alt text

It also retroactively apply Alt tags to already existing post markup.

Images without Alt Text

Uploading an image without alt text will be highlighted with the following message in preview mode on the front-end, with a prompt to take action.

This image does not have alt text. This is ok if this image is decorative only. If there are words on the image, the alt text should include those words.

Example of warning if image missing alt tag

The following options are provided to remedy this:

  • Ignore
  • Edit Alt Text
  • Mark As Decorative


This allows you to ignore the warning, removing the pop-up to take action. The warning notice is replaced with an option to Clear Ignored Issues. Selecting Clear Ignored Issues displays the warning and recommended options once again.

clear ignored issues

Edit Alt Text

Selecting Edit Alt Text takes you to Media > Alt Text where you can review any images with no alt text added, and add an alternative text description.

Alt text should not describe the image, it should describe the purpose of the image.

If the image is purely decorative and no text is required, select ‘This is a decorative image’ instead otherwise add the Alt Text.

Add Alt Text

Mark As Decorative

Often images don’t present important content and are purely decorative and used for layout or non-informative purposes. In these cases, a description of the image is not necessary or appropriate.

By selecting Mark As Decorative, an empty alt attribute value (alt=””) is added.

You can learn more on how to decide if an image is decorative here and learn more about decorative in Chapter 4 of the Complete Guide to WordPress Accessibility.

Alt text too short

While alt text should be kept as short as possible, it should still convey the meaning of the visual. If the alt text is too short, this might not convey the full meaning though.

In the following example, having an alt text of “flowers” is too short and not very helpful. Having an alt text like “field of Namaqualand flowers in bloom” is far more descriptive.

field of Namaqualand flowers in bloom

Alt text too long

Alt text that is too long could interrupt the flow for someone using a screen reader. While it is necessary to be descriptive, this should be done efficiently without using too many unnecessary words and kept under 125 characters.

Contrast Checker

The contrast checker measures the brightness between different colors. Good contrast is important for users with color blindness or other visual impairments, as it allows these users to better discern color and color differences on a web page.

The contrast checker will help you ensure the color contrast between text and background is visually accessible.

In the example below, a warning appears that there is not enough contrast between the text (#607d8b) and the background (#ffffff).

Color contrast wrong

You can learn more about contrast ratios using the following WebAim content checker. With the contrast checker tool, you are also be able to enter the exact hex values of the colors presenting the issue and make adjustments to find a more accessible color combination.

External links

Links are a basic functionality of any web content, and inaccessible links are one of the biggest barriers to accessibility.

Making sure external links are accessible is therefore one of the most important aspects of ensuring web accessibility.

Most screenreaders say “link” before each link so you should avoid language like “link” or “click here” or “read more” as these give your visitor no useful information.

Avoid using the actual URL in the text as the screen reader will read every character in the URL. If you must include a URL, include a shortened version. Instead of “Read the full article at use “read the full article at“.

Link text too short/not descriptive enough

In the following example, we are warned that the link text may be too short.

Accessibility hyperlink example

While link text should be short enough to read quickly, it should be descriptive enough to describe where the link will take you when clicked. If the link opens in a new window or tab, this should always be included in the link description.

For example, ‘click here’ and ‘read more’ is not good link text and is too short. That may present a problem for users as it doesn’t provide enough context on where the link is pointing and its purpose. Consider using link text like ‘Download the new e-book here’ or ‘Read more about extinct species here’.

Link text empty (no text)

If a link contains no text, anyone using a keyboard or screen reader will have no context as to the purpose of the link or its destination.

This error may arise if you are working with HTML in the classic editor or with an HTML block. The error message is stating that you’ve created a link using <a> tags that have no content in between. The accessibility content plugin will flag this with an [ERROR] wherever the empty link appears on the page.

To resolve this problem, navigate to the part of your document that has the error and includes descriptive link text between the <a></a> tags.

You will find a detailed introduction to Links and Hypertext here.

Links to PDF files

Not all PDF files are accessible. When adding links to a PDF file, you will receive a prompt asking to check that the PDF file is accessible, whether you can highlight any text on the PDF, or whether images include alt text.

PDF issue

This error is not highlighting something that’s wrong with the web page itself but, rather pointing out that you’ve included/shared a PDF document as a resource. When sharing resources you must ensure that are accessible as they can reduce the level of accessibility of your site.

If you created the PDF, use a guide like Adobe’s Accessibility Overview to check how you can make your PDF file more accessible. However, if you’re sharing a PDF that you did not create, you need to vet it to verify that it’s accessible before sharing it with your audience.

Elements without labels or title attributes

For someone using assistive technology such as a screen reader, elements with labels or title attributes help describe the content as well as help with navigating.

This allows a screen reader to read out the label, making it easier for a user to understand what data needs to be entered.

In the following input example, a checkbox is presented with an answer to the question “Do you like apples?” The <label> element clearly describes what is required , with the <input> element given an id attribute “apples” .

The output would look as follows:

The next example has the label omitted, with the resulting warning that the label does not seem to describe any element and will be confusing for those using screen readers.

<div class="preference">
    <label>Do you like apples?</label>
    <input type="checkbox" name="apples" id="apples">

The output, in this case, is highlighted with a warning message:

Form elements without a corresponding label element

An HTML form element represents a document section for filling out and submitting information.

A form element label allows a screen reader to read out the label, making it easier for a user to understand what data needs to be entered.

Label elements without a corresponding form element

A label element is only useful for accessibility if it contains or references the form. While it is unlikely that you’ll encounter this error since WordPress has so many easy ways to create dynamic forms. It may arise it if you try to build a form from scratch without linking the form element correctly.

Screenshot displaying a label element outside a form element.

The output with the error is highlighted below by a green border along with the corresponding error message:

Form missing label

To fix this error, verify that the form element is wrapped within the corresponding label tags.

Label error message

Frame and iframe elements without title attributes

If no title attribute is used, navigating through frames and inline frames (iframes) can become difficult and confusing.

A frame is an HTML element that defines a particular area in which another HTML document can be displayed

Note: the <frame> feature has been deprecated and is no longer recommended.

Adding a descriptive title attribute value is therefore required for those using screen readers to fully grasp the purpose of each frame.

Inline frames (or iframe) don’t usually need a descriptive title unless the content is visually distinctive. An example would be a video player or advert where a title would indicate this distinction.

To fix this warning add a title attribute within your iframe tag similar to what you see below:

<iframe src="#" title="How to peel oranges"></iframe>

List items are direct descendants of (un)ordered list elements

Descendants of list elements must be list items. This means that these descendants must be wrapped in the appropriate li tags. Anything that is not wrapped within a li tag will produce an error.

When list markup is used semantically, assistive technologies can convey information to users as they navigate to and within lists, such as the total number of items and the relative position of each item in the list. Assistive technologies also have useful features like “go to next item”, “next list”, etc. Therefore, if the descendants are not marked up correctly, it will cause confusion for users and reduce the accessibility of the page.

In our example below we have three descendants that are wrapped in a div, p, and li tag respectively. The first two are invalid as displayed in the output and corresponding error message.

Example of invalid list
List error message

To fix this error, ensure that all descendants of ul and ol elements are wrapped in <li></li> tags.

Heading Tags

Headings are used to create page outlines, making it easier to find what you want on the page. This also allows users of screen readers and other assistive technology to skip from one heading to another.

A page should ideally only have one H1 header, which would be the page or post title.

Headings H2 through to H6 represent different levels or “indentations” to create a page outline.

Multiple H1 Headings

If multiple H1 heading tags are used, or if an H1 tag is used other than as a page or post title, a warning will be displayed prompting to change the content H1 tag to an H2 tag.

Skipped Headings

When heading tags are skipped, for example, if headings H2 and H4 are used but not H3, this makes it harder for visitors with screen readers to navigate the page.

You shouldn’t be selecting headings based on appearance. The heading should be selected on the appropriate heading rank in your hierarchy.

You will receive a prompt to review headings to ensure none are skipped.

Heading warning

This issue is fixed by changing the H4 to H3.

Data Tables

Data tables are used to present information in a grid format with columns and rows, allowing sighted users to visually scan a table.

Users with screen readers, who can’t see the table, navigate one cell at a time while column and row headers are spoken to them.

Tables without a caption or summary

Data tables should have a brief description or caption indicating the contents of that table. While it is not always necessary to have a caption, it is helpful, and when used should be added to the caption element of the table.

To fix this error, you’ll need to navigate to the table block presenting the problem and add a caption below the table. The caption should explain briefly the purpose of the table.

Table Row and Column Headers

Table headers should never be empty, with a row and/or column header essential to creating accessible data tables. This includes the top-left cell of some tables.

A table example

To fix this error, click on the table and navigate to the left side of your screen and activate the ‘Header Section‘ setting under Table settings. A header panel will then be added to the table where you can add descriptive labels such as ‘Names, Breed, Schools, Address, etc.’

Screenshot with 'header section' setting active.

Unique IDs (all elements that have IDs must have unique IDs)

The id attribute is used to specify a unique id for an HTML element. The value of the id attribute must be unique within the HTML document. The id attribute can be used in both CSS and JavaScript. In CSS, it is used to point to a specific style declaration in a style sheet. While in JavaScript, it’s used to access and manipulate the element with the specific id.

Whenever there are duplicate IDs it can create problems for assistive technologies and can lead to other instances following the first use to be overlooked.

The plugin will help you to spot these duplicates if any and help you to resolve the issue. In the image below, we have made this error deliberately. There are two h2 elements using the id ‘heading’:

Screenshot showing duplicate identifiers being used.
Error highlighting h2 elements that are using the same id

The plugin will thus give us the following duplicate id error, ‘The value of an id attribute must be unique to prevent other instances from being overlooked by assistive technologies:

The value of an id attribute must be unique to prevent other instances from being overlooked by assistive technologies

To fix this error, ensure that the IDs being used are unique for each element.

Video elements with no captions/subtitles

Video content has become one of the most common methods of sharing information. But, video content as is without captions or subtitles can be limiting for some users.

Providing synchronized captions, audio descriptions, transcripts provides a way for users who cannot hear or see the content to understand the content. Also, consider users with learning disabilities or slow internet connections – captions/subtitles provide an alternate way to process that information.

If your video is missing captions or subtitles you will receive the following error:

There are no captions or subtitles detected for this video. All videos must include captions or subtitles.

To fix this error, add subtitle files or captions to your video using a tool like Google Drive’s ‘Manage caption tracks’ feature.