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 editorAlt + F10
to focus the editor's toolbar- Arrow keys to navigate the toolbar
Enter
to select a menu itemTab
orEsc
to navigate back the editor content
Shift + Arrow keys
to select textTab
to navigate to the text selection menuEnter
to select a menu itemTab
orEsc
to navigate back to the editor content
Enter
to create a new paragraphTab
to navigate to the insert content menu- Arrow keys to navigate the toolbar
Enter
to select a menu item, inserting the contentTab
orEsc
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
Document | Section | Heading |
---|---|---|
WCAG 3.0 | 7.1 | Text Alternatives |
WCAG 2.1 | 1.1.1 | Non-text Content |
WCAG 2.1 | 2.1 | Keyboard Accessible |
WCAG 2.1 | 2.1.1 | Keyboard |
WCAG 2.1 | 4.1.1 | Parsing |
WCAG 2.1 | 4.1.2 | Name, Role, Value |
WCAG 2.1 | 2.1.2 | No Keyboard Trap |