Accessibility Checker plugin

This plugin is only available for paid TinyMCE subscriptions.

The a11ychecker premium plugin allows you to check the HTML in the editor for various WCAG & Section 508 accessibility problems. It has an auto-repair feature that lets the user fix identified problems.

Interactive example

  • TinyMCE

  • HTML

  • JS

  • Edit on CodePen

<textarea id="a11ychecker">
  <p><strong>Introduction</strong></p>
  <p>Note: This demo has been crafted to intentionally trigger most of our accessibility rules for demonstration purposes.</p>
  <hr>
  <h2><a id="example"></a>The Tiny Logo</h2>
  <p><a href="https://www.tiny.cloud/docs/tinymce/6/a11ychecker/#liveexample" target="_blank" rel="noopener"><img src="https://www.tiny.cloud/docs/images/logos/android-chrome-256x256.png" alt="" width="128" height="128"></a><a href="https://www.tiny.cloud/docs/tinymce/6/a11ychecker/#liveexample" target="_blank" rel="noopener">This is a link to this demo. The same link has been added to logo to the left.</a></p>
  <p>* This is a list.</p>
  <p>* That has been poorly formatted.</p>
  <p>* By using asterisks, instead of using &lt;ul&gt;&lt;li&gt; elements.</p>
  <h4><a id="example"></a>To create an <strong>inaccessible</strong> ordered list:</h4>
  <p>1. Pick a ordering scheme,</p>
  <p>2. Type the item number manually for each item,</p>
  <p>3. Don't use &lt;ol&gt;&lt;li&gt; elements.</p>
  <p>This sentence contains some words that have <span style="background-color: #5a5a5a;">low color contrast</span>, which makes them <span style="color: #ced4d9;">difficult to read</span>.</p>
  <h3>An inaccessible table</h3>
  <p>The below table is missing a caption and table header cells (&lt;th&gt; elements).</p>
  <table style="border-collapse: collapse; width: 100%;" border="1">
  <tbody>
  <tr>
  <td style="width: 31.819%;">&nbsp;</td>
  <td style="width: 31.819%;">&nbsp;</td>
  <td style="width: 31.819%;">&nbsp;</td>
  </tr>
  <tr>
  <td style="width: 31.819%;">&nbsp;</td>
  <td style="width: 31.819%;">&nbsp;</td>
  <td style="width: 31.819%;">&nbsp;</td>
  </tr>
  <tr>
  <td style="width: 31.819%;">&nbsp;</td>
  <td style="width: 31.819%;">&nbsp;</td>
  <td style="width: 31.819%;">&nbsp;</td>
  </tr>
  </tbody>
  </table>
  <p>&nbsp;</p>
</textarea>
tinymce.init({
  selector: 'textarea#a11ychecker',
  plugins: 'a11ychecker advcode table advlist lists image media anchor link autoresize',
  toolbar: 'a11ycheck | blocks bold forecolor backcolor | bullist numlist | link image media anchor | table | code',
  a11y_advanced_options: true,
  a11ychecker_html_version: 'html5',
  a11ychecker_level: 'aaa',
  content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }'
});

Basic setup

To add the Accessibility Checker plugin to the editor, add a11ychecker to the plugins option in the editor configuration.

For example:

tinymce.init({
  selector: 'textarea',
  plugins: 'a11ychecker',
  toolbar: 'a11ycheck'
});

Accessibility Rules

The following checks are available for the Accessibility Checker plugin. The rules checked depends on:

  • The level of compliance (A, AA, or AAA), set using the a11ychecker_level option.

  • The HTML version of the content, set using the a11ychecker_html_version option.

Each rule has a severity level, which will be one of the following, listed in order of increasing severity:

  • Warning

  • Error

D1 - Usage of paragraphs as headings

Rule description: this rule checks that h1-h6 tags are used for heading content, not p tags. Not using correct heading markup will make it difficult for assistive technologies to represent and navigate through your content.

Accessibility Checker rule details - D1

Notification level (severity)

Warning

WCAG level

Level A ; Level AA ; Level AAA

HTML version

HTML4 and HTML5

WCAG 2.1 specifications

D2 - Sequential headings

Rule description: this rule checks that headings tags are used sequentially.

For example: A h1 heading should be followed by a h2 heading, not a h3 heading. Using sequential headings will make it easier for assistive technology to parse your content.

Accessibility Checker rule details - D2

Notification level (severity)

Error

WCAG level

Level A ; Level AA ; Level AAA

HTML version

HTML4 and HTML5

WCAG 2.1 specification

G141 - Organizing a page using headings.

D3 - Adjacent links

Rule description: this rule checks that links next to other links do not have the same href attribute.

For example: If an image link and a text link have the same href attribute, both elements should be in the same a element. If an image link and a text link point to the same URL but are two separate elements, it can be confusing for users of screen readers and other assistive technologies.

Accessibility Checker rule details - D3

Notification level (severity)

Error

WCAG level

Level A ; Level AA ; Level AAA

HTML version

HTML4 and HTML5

WCAG 2.1 specification

H2 - Combining adjacent image and text links for the same resource.

D4O - Ordered list structure

Rule description: this rule checks that an ol element is used for ordered lists. Do not use paragraphs beginning with numbers or roman numerals instead of an ol element containing li items. This is to simplify navigation and parsing of the content for users of assistive technologies.

Accessibility Checker rule details - D4O

Notification level (severity)

Error

WCAG level

Level A ; Level AA ; Level AAA

HTML version

HTML4 and HTML5

WCAG 2.1 specification

H48 - Using ol, ul and dl for lists or groups of links.

D4U - Unordered list structure

Rule description: this rule checks that a ul element is used for unordered lists. Do not use paragraphs beginning with * or - or some similar character instead of an ol element containing li items. This is to simplify navigation and parsing of the content for users of assistive technologies.

Accessibility Checker rule details - D4U

Notification level (severity)

Error

WCAG level

Level A ; Level AA ; Level AAA

HTML version

HTML4 and HTML5

WCAG 2.1 specification

H48 - Using ol, ul and dl for lists or groups of links.

D5 - Contrast ratio of the text (D5A, D5B, and D5C)

Rule description: this rule checks that the contrast ratio of the text is above the following values:

  • When the compliance level is set to AA,

    • 4.5:1 for normal text

    • 3:1 for large text

  • When the compliance level is set to AAA,

    • 7:1 for any text

Text with a low contrast ratio is hard to read for users with impaired vision.

Accessibility Checker rule details - D5A

Notification level (severity)

Error

WCAG level

Level AA

HTML version

HTML4 and HTML5

WCAG 2.1 specification

G145 - Ensuring that a contrast ratio of at least 3:1 exists between text (and images of text) and background behind the text.

Accessibility Checker rule details - D5B

Notification level (severity)

Error

WCAG level

Level AA

HTML version

HTML4 and HTML5

WCAG 2.1 specification

G18 - Ensuring that a contrast ratio of at least 4.5:1 exists between text (and images of text) and background behind the text.

Accessibility Checker rule details - D5C

Notification level (severity)

Error

WCAG level

Level AAA

HTML version

HTML4 and HTML5

WCAG 2.1 specification

G17 - Ensuring that a contrast ratio of at least 7:1 exists between text (and images of text) and background behind the text.

H93 - IDs must be unique

Rule description: this rule checks that all id attributes are unique in the editor. Duplicate id attributes are known to cause problems for assistive technologies when parsing the content.

Accessibility Checker rule details - H93

Notification level (severity)

Error

WCAG level

Level A ; Level AA ; Level AAA

HTML version

HTML4 and HTML5

WCAG 2.1 specification

H93 - Ensuring that id attributes are unique on a Web page.

I1 - Image alt text

Rule description: this rule checks that all images have alternative (alt) text for screen readers and other assistive technologies.

Accessibility Checker rule details - I1

Notification level (severity)

Error

WCAG level

Level A ; Level AA ; Level AAA

HTML version

HTML4 and HTML5

WCAG 2.1 specification

G95 - Providing short text alternatives that provide a brief description of the non-text content.

In TinyMCE 6.3 and later, rule I3 can also be applied. If applied, an Image alternative text should be less than 100 characters warning dialog presents if the alternative (alt) text is longer than 100 characters. This dialog also presents the alternative text in an editable field, for immediate repair.

I2 - Image alt text is not the image filename

Rule description: this rule checks that the alt attribute text of the image is not the same as the filename of the image.

Accessibility Checker rule details - I2

Notification level (severity)

Error

WCAG level

Level A ; Level AA ; Level AAA

HTML version

HTML4 and HTML5

WCAG 2.1 specification

G95 - Providing short text alternatives that provide a brief description of the non-text content.

In TinyMCE 6.3 and later, rule I3 can also be applied. If applied, an Image alternative text should be less than 100 characters warning dialog presents if the alternative (alt) text is longer than 100 characters. This dialog also presents the alternative text in an editable field, for immediate repair.

I3 - Image alt text is not greater than 100 characters

Rule description: this rule checks that the alt attribute text of the image is not more than 100 characters.

An Image alternative text should be less than 100 characters warning dialog presents if the alternative (alt) text is longer than 100 characters. This dialog also presents the alternative text in an editable field, for immediate repair.

Accessibility Checker rule details - I3

Notification level (severity)

Warning

WCAG level

Level A ; Level AA ; Level AAA

HTML version

HTML4 and HTML5

WCAG 2.1 specification

n/a.

This feature is only available for TinyMCE 6.3 and later.

T1 - Table caption

Rule description: this rule checks that all table elements have a caption element describing the data inside the table to simplify parsing and navigation of the content for users of assistive technologies.

Accessibility Checker rule details - T1

Notification level (severity)

Error

WCAG level

Level A ; Level AA ; Level AAA

HTML version

HTML4 and HTML5

WCAG 2.1 specification

H39 - Using caption elements to associate data table captions with data tables.

T2 - Complex table summary

Rule description: this rule checks that all complex tables must have a summary attribute explaining to users of assistive technologies how to navigate through the data inside of the table.

This rule only applies to HTML 4 content and is not checked when a11ychecker_html_version is set to html5.

Accessibility Checker rule details - T2

Notification level (severity)

Warning

WCAG level

Level A ; Level AA ; Level AAA

HTML version

HTML4

WCAG 2.1 specification

H73 - Using the summary attribute of the table element to give an overview of data tables.

T3 - Table caption and summary

Rule description: this rule checks that the table caption and summary does not have the same text content. The caption should explain what the table is about while the summary should explain how to navigate the data inside of the table.

The table summary attribute was deprecated in HTML 5, both the what and how information should be moved to the table caption.

Accessibility Checker rule details - T3

Notification level (severity)

Error

WCAG level

Level A ; Level AA ; Level AAA

HTML version

HTML4 and HTML5

WCAG 2.1 specification

H73 - Using the summary attribute of the table element to give an overview of data tables.

T4A - Table markup

Rule description: this rule checks that all tables contain both tr and td elements.

Accessibility Checker rule details - T4A

Notification level (severity)

Error

WCAG level

Level A ; Level AA ; Level AAA

HTML version

HTML4 and HTML5

WCAG 2.1 specification

H51 - Using table markup to present tabular information.

T4B - Table headers

Rule description: this rule checks that all table elements contain at least one table header (th) element.

Accessibility Checker rule details - T4B

Notification level (severity)

Error

WCAG level

Level A ; Level AA ; Level AAA

HTML version

HTML4 and HTML5

WCAG 2.1 specification

H51 - Using table markup to present tabular information.

T4C - Table heading scope

Rule description: this rule checks that all table header (th) elements have a scope attribute clarifying what scope the heading has inside of the table. The allowed values are row, col, rowgroup, and colgroup. This is important for users of assistive technologies to be able to parse table data.

Accessibility Checker rule details - T4C

Notification level (severity)

Error

WCAG level

Level A ; Level AA ; Level AAA

HTML version

HTML4 and HTML5

WCAG 2.1 specification

H63 - Using the scope attribute to associate header cells and data cells in data tables.

Options

The following configuration options affect the behavior of the Accessibility Checker plugin.

a11y_advanced_options

This option affects the functionality of:

Setting a11y_advanced_options to true:

  • Adds the Image is decorative option to the Insert/Edit Image dialog, allowing users to specify that an image is decorative and does not require alternative text for accessibility purposes.

  • Adds the Decorative image button to Image Optimizer’s Alt text context toolbar, allowing users to specify that an image is decorative and does not require alternative text for accessibility purposes.

  • Adds the Image is decorative option to the Accessibility Checker error dialog for images without alternative text or the role="presentation" attribute.

If a11ychecker_allow_decorative_images is not explicitly set, the value defined in a11y_advanced_options will be used.

Type: Boolean

Default value: false

Possible values: true, false

Example: using a11y_advanced_options

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'a11ychecker',
  toolbar: 'a11ycheck',
  a11y_advanced_options: true,
});

a11ychecker_allow_decorative_images

This option sets whether the Accessibility Checker should allow decorative images. When this option is set to true, a decorative image must have both:

  • An empty alternative text attribute.

  • The role="presentation" attribute.

For example:

<img src="my-image.png" role="presentation" alt="" />

If a11ychecker_allow_decorative_images is set to true, the Accessibility Checker will present an error when:

  • An image does not have the alternative text attribute (alt).

  • An image has an empty alternative text attribute, but is missing the role="presentation" attribute.

  • An image has alternative text and a conflicting role="presentation" attribute.

If a11ychecker_allow_decorative_images is set to false, the Accessibility Checker will present an error when:

  • An image does not have the alternative text attribute (alt).

  • An image has an empty alternative text attribute.

  • An image has the role="presentation" attribute.

If a11ychecker_allow_decorative_images is not explicitly set, the value defined in a11y_advanced_options will be used.

Type: Boolean

Default value: false

Possible values: true, false

Example: using a11ychecker_allow_decorative_images

tinymce.init({
  selector: 'textarea',
  plugins: 'a11ychecker',
  toolbar: 'a11ycheck',
  a11ychecker_allow_decorative_images: true
});

a11ychecker_filter_issue

The a11ychecker_filter_issue option allows Accessibility Checker issues to be removed from the Accessibility Checker report using a callback function. This option is a flexible alternative to the a11ychecker_ignored_rules option. This option can remove issues from the results shown in the dialog and the getReport API.

The callback function will be passed issue objects generated by the getReport() API. To remove an issue from the Accessibility Checker report the callback needs to return false for that particular issue.

Type: Function

Default value:

(issue) => true;

Example: using a11ychecker_filter_issue to filter out the Accessibility Checker T1 rule

The callback function in the following example will return false if the issue id value is 'T1', filtering 'T1' issues from the Accessibility Checker report.

tinymce.init({
  selector: 'textarea',  // change this value according to your html
  plugins: 'a11ychecker',
  toolbar: 'a11ycheck',
  a11ychecker_filter_issue: (issue) => {
    return issue.id !== 'T1';
  }
});

Example: using a11ychecker_filter_issue to filter out all Accessibility Checker table rules and rules less than 'error' level

The callback function in the following example will only return false if the issue element is a 'table' and the 'severity' level is not 'error', filtering all low-severity and table element-related issues from the Accessibility Checker report.

tinymce.init({
  selector: 'textarea',  // change this value according to your html
  plugins: 'a11ychecker',
  toolbar: 'a11ycheck',
  a11ychecker_filter_issue: (issue) => {
	  return !(issue.element.nodeName.toLowerCase() === 'table' || issue.severity !== 'error');
  }
});

Example: using a11ychecker_filter_issue to filter images with empty alternative text from the Accessibility Checker I1 rule

The callback function in the following example will only return false for any issues with 'I1' as the 'id' image elements with an empty +'alt+' attribute, otherwise the issue won’t be filtered out. This implementation can be useful as allowing images to have empty alternative text can be another method of applying the role="presentation" attribute to mark an image as decorative.

tinymce.init({
  selector: 'textarea',  // change this value according to your html
  plugins: 'a11ychecker',
  toolbar: 'a11ycheck',
  a11ychecker_filter_issue: (issue) => {
    const element = issue.element;
    const isImageAndI1Issue = issue.id === 'I1' && element.nodeName.toLowerCase() === 'img';
    const hasEmptyAltAttribute = element.hasAttribute('alt') && element.alt === '';
    return !(isImageAndI1Issue && hasEmptyAltAttribute);
  }
});

a11ychecker_html_version

This configuration option sets the HTML version to use when checking issues.

For example: Setting the version to HTML 4 will enable the rule "Complex tables should have summaries", where summary is a valid attribute in HTML 4 but not HTML 5.

Type: String

Default value: html5

Possible values: html4, html5

Example: using a11ychecker_html_version

tinymce.init({
  selector: 'textarea',
  plugins: 'a11ychecker',
  toolbar: 'a11ycheck',
  a11ychecker_html_version: 'html4'
});

a11ychecker_ignored_rules

The a11ychecker_ignored_rules option prevents specific Accessibility Checker rules from being checked. This feature allows developers to skip rules that they do not wish to check. For example: To skip rules that flag known content issues or custom HTML that should not be checked.

Type: A comma-separated string.

Default value: ''

Possible values: 'D1', 'D2', 'D3', 'D4O', 'D4U', 'D5A', 'D5B', 'D5C', 'H93', 'I1', 'I2', 'T1', 'T2', 'T3', 'T4A', 'T4B', 'T4C'

Example: using a11ychecker_ignored_rules

This examples shows how to ignore the following checks (rules):

  • D2 - Sequential headings

  • I2 - Image alt text is not the image filename

  • T4B - Table headers

tinymce.init({
  selector: 'textarea',  // change this value according to your html
  plugins: 'a11ychecker',
  toolbar: 'a11ycheck',
  a11ychecker_ignored_rules: 'D2, I2, T4B'
});

a11ychecker_issue_url_callback

The a11ychecker_issue_url_callback option is used to change the target URL for the "Click for more info" button (help icon - a question mark inside a circle) in the Accessibility Checker dialog. By default, the "more info" links will point to https://www.tiny.cloud/docs/tinymce/7/a11ychecker/#<ruleId>, such as https://www.tiny.cloud/docs/tinymce/7/a11ychecker/#D1. This option can be used to set the target URL to a page or pages outside https://www.tiny.cloud/docs/.

Type: Function

Default value:

(ruleId) => `https://www.tiny.cloud/docs/tinymce/6/a11ychecker/#${ruleId}`

Example: using a11ychecker_issue_url_callback

This example shows how to change the link for the "Click for more info" button (help icon - a question mark inside a circle) on the Accessibility Checker dialog to point to anchors at www.example.com/tinymce/a11ychecker/more_info.

tinymce.init({
  selector: 'textarea',  // change this value according to your html
  plugins: 'a11ychecker',
  toolbar: 'a11ycheck',
  a11ychecker_issue_url_callback: (ruleId) =>
    `https://www.example.com/tinymce/a11ychecker/more_info#${ruleId}`
});

a11ychecker_level

This configuration option sets the WCAG level to use when checking issues.

For example, the "Text must have a contrast ratio of at least …​" rule:

  • When using AA, Accessibility Checker will check that the contrast ratio is not less than 4.5:1.

  • When using AAA, Accessibility Checker will check that the contrast ratio is not less than 7.0:1.

Type: String

Default value: aa

Possible values: a, aa, aaa

Example: using a11ychecker_level

tinymce.init({
  selector: 'textarea',
  plugins: 'a11ychecker',
  toolbar: 'a11ycheck',
  a11ychecker_level: 'aaa'
});

Toolbar buttons

The Accessibility Checker plugin provides the following toolbar buttons:

Toolbar button identifier Description

a11ycheck

Opens the accessibility checker dialog.

These toolbar buttons can be added to the editor using:

The Accessibility Checker plugin provides the following menu items:

Menu item identifier Default Menu Location Description

a11ycheck

Tools

Opens the accessibility checker dialog.

These menu items can be added to the editor using:

Events

The Accessibility Checker plugin provides the following events.

Name Data Description

A11ycheckStart

N/A

Fired when the Accessibility Checker is opened

A11ycheckStop

N/A

Fired when the Accessibility Checker is closed

A11ycheckIgnore

N/A

Fired when the Ignore button is pressed

A11ycheckRepair

N/A

Fired when the Repair button is pressed

A11ycheckShowDetails

N/A

Fired when the Click for more info button is pressed

APIs

The Accessibility Checker plugin provides the following APIs.

toggleaudit()

Opens and closes the accessibility checker dialog with the results of the audit and options to correct the problems, if any.

Example: using toggleaudit()

tinymce.activeEditor.plugins.a11ychecker.toggleaudit();

getReport()

Conducts an accessibility audit and reports the results without opening the dialog. The report produced is an array of objects, where each object represents an issue.

Example: using getReport()

const issues = tinymce.activeEditor.plugins.a11ychecker.getReport();

console.log(issues);

// Example result
[
  {
    "contentID": "<div id=\"accessibility-issue__contentID\"><span>Text:&nbsp;</span><span>\"H5\"</span></div>",
    "description": "Headings must be applied in sequential order. For example: Heading 1 should be followed by Heading 2, not Heading 3.",
    "element": h5, // reference to the DOM element where the issue was found
    "id": "D2",
    "severity": "error",
    "url": "https://www.w3.org/WAI/WCAG21/Techniques/general/G141.html",
  },
  {
    "contentID": "<div id=\"accessibility-issue__contentID\"><span>Table:&nbsp;</span><span>\"2x2\"</span></div>",
    "description": "Tables must have captions",
    "element": table, // reference to the DOM element where the issue was found
    "id": "T1",
    "severity": "error",
    "url": "https://www.w3.org/WAI/WCAG21/Techniques/html/H39.html",
  }
]

The issue object

In a11ychecker, when the content within the editor is audited, each element is checked to ensure that no Accessibility rules are violated. Any element which doesn’t adhere to a rule will generate an issue within the audit; the details of which are to be displayed in the a11ychecker dialog.

The 'issue' object provides relevant data pertaining to any issue generated by an element which violates an Accessibility rule:

  • id : String A11ychecker issue identifier used by TinyMCE, such as D1, T4A. For a description and other details about the issue, see Accessibility Rules.

  • description : String description of the issue; as will be displayed in the dialog.

  • severity : String severity level of the issue; either warning or error.

  • url : String URL reference for the issue. By default, this will be a link to the W3 website, containing the W3 WCAG technique that needs to be addressed to clear the issue.

  • element : Object DOM element where the issue was found.

  • contentID : String A short snippet of the content (such as text, link, image, or table) where the issue was found.