Important changes to Tiny Cloud pricing > Find out more

NOTE: TinyMCE 5 reached End of Support in April 2023. No more bug fixes, security updates, or new features will be introduced to TinyMCE 5. We recommend you upgrade to TinyMCE 6 or consider TinyMCE 5 Long Term Support (LTS) if you need more time.

Accessibility Checker plugin

Checks the contents of the editor for WCAG & Section 508 accessibility problems.

Contribute to this page

Note: 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

Basic setup

To add the A11yChecker 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 A11yChecker 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:

  • Information
  • 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.

A11yChecker rule details - D1

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.

A11yChecker rule details - D2

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.

A11yChecker rule details - D3

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.

A11yChecker rule details - D4O

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.

A11yChecker rule details - D4U

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.

A11yChecker rule details - D5A

A11yChecker rule details - D5B

A11yChecker rule details - D5C

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.

A11yChecker rule details - H93

I1 - Image alt text

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

A11yChecker rule details - I1

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.

A11yChecker rule details - I2

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.

A11yChecker rule details - T1

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.

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

A11yChecker rule details - T2

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.

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

A11yChecker rule details - T3

T4A - Table markup

Rule description: This rule checks that all tables contain both td and th elements.

A11yChecker rule details - T4A

T4B - Table headers

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

A11yChecker rule details - T4B

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.

A11yChecker rule details - T4C

Configuration Options

The following configuration options affect the behavior of the A11yChecker plugin.

a11y_advanced_options

This option affects the functionality of:

  • The Accessibility Checker plugin (a11ychecker).
  • The Image plugin (image).

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 Image is decorative option to the Accessibility Checker error dialog for images without alternative text or the role="presentation" attribute.

Important: When a11y_advanced_options is set to true, a11ychecker_allow_decorative_images will default to true.

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',
  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.

Note: If a11y_advanced_options is set to true, a11ychecker_allow_decorative_images will default to true.

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 function will be passed the results of the getReport() API. To filter an issue from the Accessibility Checker report, the callback needs to return false for that particular issue.

Type: Function

Default Value:

function(issue) {
  return 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: function(issue) {
    return issue.id !== 'T1';
  }
});

Example: Using a11ychecker_filter_issue to filter out all Accessibility Checker table rules

The callback function in the following example will return false if the issue element value is 'table', filtering all 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: function(issue) {
    return issue.element.nodeName.toLowerCase() !== 'table';
  }
});

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: html4

Possible Values: html4, html5

Example: Using a11ychecker_html_version

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

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/plugins/a11ychecker/#<ruleId>, such as https://www.tiny.cloud/docs/plugins/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: undefined

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: function (ruleId) {
    return `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 A11yChecker 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:

Menu items

The A11yChecker 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:

APIs

The A11yChecker 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()

editor.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 and contains the following details:

  • id - The issue identifier used by TinyMCE, such as D1, T4A. For a description and other details about the issue, see Accessibility Rules.
  • description - A description of the issue.
  • severity - The severity of the issue, either: info, warning, or error.
  • element - The DOM element where the issue was found.
  • url - A URL to the W3 WCAG technique that needs to be addressed to clear the issue.

Example: Using getReport()

var issues = editor.plugins.a11ychecker.getReport();

console.log(issues);

// example result
[
  {
    "id": "D2",
    "severity": "error",
    "url": "http://www.w3.org/TR/UNDERSTANDING-WCAG20/content-structure-separation-programmatic.html",
    "description": "Headings must be applied in sequential order. For example: Heading 1 should be followed by Heading 2, not Heading 3.",
    "element": {}  // The element value contains the DOM element (such as <h4>).
  },
  {
    "id": "T1",
    "severity": "error",
    "url": "http://www.w3.org/TR/UNDERSTANDING-WCAG20/content-structure-separation-programmatic.html",
    "description": "Tables must have captions",
    "element": {}  // The element value contains the DOM element (such as <table>).
  }
]

Can't find what you're looking for? Let us know.

Except as otherwise noted, the content of this page is licensed under the Creative Commons BY-NC-SA 3.0 License, and code samples are licensed under the Apache 2.0 License.