Accessibility options

This page describes configuration options that affect how TinyMCE supports keyboard users and screen readers. For guidance on using the editor with the keyboard, see the How to use the editor section that follows.

How to use the editor

TinyMCE supports full keyboard navigation. Users can access the menu bar, toolbars, and contextual toolbars without using a mouse.

The editor provides two main ways to access formatting and editing features:

  • Menu bar: Use the menu bar when the desired command is known. Menus group related actions and can be faster to navigate for experienced users.

  • Toolbars: Use the main toolbar for frequently used actions. Toolbar buttons are visible by default and provide quick access to common formatting options.

  • Contextual toolbars: Some actions are available only from contextual toolbars that appear when the cursor is on specific content, such as images, links, or tables.

When a feature appears only in a contextual toolbar (for example, editing alternative text for an image), use the keyboard shortcut to focus the contextual toolbar. See the table below.

Keyboard shortcuts for editor navigation

Action Windows or Linux macOS

Focus the menu bar

Alt+F9

⌥+F9

Focus the toolbar

Alt+F10

⌥+F10

Focus the element path (footer)

Alt+F11

⌥+F11

Focus notifications

Alt+F12

⌥+F12

Focus the contextual toolbar

Ctrl+F9

Ctrl+F9

Open the Help dialog

Alt+0

⌥+0

The contextual toolbar appears when the cursor is on content that has context-specific actions, such as an image or a link. For example, to edit alternative text for an image using only the keyboard:

  1. Place the cursor on the image.

  2. Press Ctrl+F9 (Windows, Linux, or macOS) to focus the contextual toolbar.

  3. Use the arrow keys to move to the desired button (for example, Image options or Alternative description).

  4. Press Enter or Space to activate the button.

Screen readers

TinyMCE works with common screen readers, including VoiceOver (macOS and iOS), JAWS, and NVDA. The Help plugin provides a Keyboard Navigation tab that documents the full keyboard navigation model. When the Help plugin is loaded, the shortcut to open the Help dialog (Alt+0 or ⌥+0) appears in the status bar by default.

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 Media 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 that need to be marked as decorative.

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 image',
  toolbar: 'a11ycheck image',
  a11y_advanced_options: true,
});

highlight_on_focus

In TinyMCE 7.0, the default setting for highlight_on_focus was changed from false to true. Any editors using this highlight_on_focus: true option in TinyMCE , can remove this option from their TinyMCE init configuration when upgrading to TinyMCE 7.0.

The highlight_on_focus option adds a blue outline to an instantiated TinyMCE editor when that editor is made the input focus. When using the oxide-dark skin, the outline is white.

This allows users to clearly see when the editor is in focus, or which editor has focus if more than one TinyMCE instance is available.

Type: Boolean

Default value: true

Possible values: true, false

Example: using highlight_on_focus

tinymce.init({
  selector: "textarea",
  highlight_on_focus: false
});

Using highlight_on_focus with custom skins

If a custom skin is being used, two variables can be updated to match the highlight_on_focus option’s appearance with the custom skin.

The two rules and their default values are:

@edit-area-border-color: #2D6ADF;
@edit-area-border-width: 2px;
This is entirely optional. If the default values are not changed, the highlight_on_focus option works with a custom skin exactly as it does with TinyMCE default skins.

iframe_aria_text

This option is used to customize the title attribute on the TinyMCE iframe element. For example:

<iframe title="Rich Text Area. Press ALT-0 for help."></iframe>

The title attribute is read by screen-readers to help users identify the editor. This option only applies to TinyMCE classic (iframe) mode and has no effect on inline editors.

Type: String

Default value: 'Rich Text Area. Press ALT-0 for help.'

Example: using iframe_aria_text

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  iframe_aria_text: 'Text Editor'
});

The iframe_aria_text option is applied differently depending on the browser to ensure consistent screen reader announcements:

  • Firefox: The title attribute is set on the iframe element. The aria-label on the body is not set.

  • Other browsers: The aria-label is set on the body inside the iframe. The title is not set on the iframe.

Tab order

The tab order of the elements in a page, including TinyMCE, should be configured by setting the tabindex attribute on the relevant HTML elements. The browser will then natively handle the tab order.

To configure tabindex for the TinyMCE editor, set the attribute on the target element for the editor.

In iframe (classic editor) mode, TinyMCE will copy the tabindex attribute from the target element to the editor’s iframe, to allow this to work correctly.

Example: configuring tab order

<script>
tinymce.init({
  selector: 'textarea'
});
</script>
...
<input tabindex="1">
<textarea tabindex="2"></textarea>
<input tabindex="3">

help_accessibility

When the Help plugin is loaded, the TinyMCE editor displays the keyboard shortcut for accessing the Help dialog in the TinyMCE status bar by default.

The help_accessibility option allows for this display to be turned off.

Type: Boolean

Default value: true

Possible values: true, false

Example: turning help_accessibility off

tinymce.init({
  selector: "textarea",  // change this value according to your HTML
  plugins: "help",
  help_accessibility: false,
});

Example: explicitly turning help_accessibility on

The help_accessibility option is set to true by default when the Help plugin is loaded.

It is not necessary, but may be useful, to explicitly set the option to true.

tinymce.init({
  selector: "textarea",  // change this value according to your HTML
  plugins: "help",
  help_accessibility: true,
});