How to make your editor accessible

We strive to make Tiptap accessible to everyone. But this is at odds with the fact that we are a headless editor. We don’t provide an interface, so it’s up to you to make sure that the editor is accessible. Here are some guidelines to help you with that.

Demo of an accessible editor

Guidelines

Here are a non-exhaustive list of guidelines to make your editor accessible:

Keyboard accessibility

Make sure that all editor features are accessible via the keyboard. This includes navigating the editor, selecting text, menus, and using all editor features. If you look at the demo above, you can see that you can navigate the editor with the keyboard by:

• Tab to focus within the editor
• Alt + F10 to focus the editor's toolbar
  • Arrow keys to navigate the toolbar
  • Enter to select a menu item
  • Tab or Esc to navigate back the editor content
• Shift + Arrow keys to select text
  • Tab to navigate to the text selection menu
  • Enter to select a menu item
  • Tab or Esc to navigate back to the editor content
• Enter to create a new paragraph
  • Tab to navigate to the insert content menu
    • Arrow keys to navigate the toolbar
    • Enter to select a menu item, inserting the content
    • Tab or Esc to navigate back to the editor content
• All other editor keyboard shortcuts as described in the keyboard shortcuts

Semantic markup & Aria Roles

All of the default Tiptap extensions produce semantic markup. This means that the editor produces HTML that is easy to understand for screen readers.

To help screen readers even more, your editor & menus should provide appropriate Aria roles. Some examples are:

• The editor should have the role="textbox"
• The toolbar should have the role="toolbar"
• The menu should have the role="menu"
• The menu items should have the role="menuitem"

Interface

An interface needs to have well-defined contrasts, big enough click areas. Currently, we don’t provide an interface, so for now that’s totally up to you.

Gotchas

We've found a few gotchas, when implementing accessibility, that you should be aware of:

VoiceOver concatenates words across block elements

When using VoiceOver on macOS, it is important to be aware that it may concatenate words across block elements. This can lead to unexpected reading experiences for users relying on screen readers.

For example, consider the following HTML structure:

<h1>Heading</h1>
<p>Paragraph</p>

VoiceOver would read this as "HeadingParagraph" instead of "Heading Paragraph" (notice the space). To fix this, you can add a zero-width space after each block element:

.tiptap {
  h1::after,
  h2::after,
  h3::after,
  h4::after,
  h5::after,
  h6::after,
  p::after {
    content: '\200B';
  }
}

Keyboard traps

A keyboard trap is a situation where a user can’t navigate away from a certain element using the keyboard. This can be a problem if you have a modal or a menu that can be opened with the keyboard. Make sure that the user can always navigate away from these elements.

Writing assistance (optional)

An optional writing assitance could help people writing content semanticly correct, for example pointing out an incorrect usage of heading levels. With that kind of assistance provided by the core developers, we could help to improve the content of a lot of applications.

Resources