How to develop a custom menu

Tiptap comes very raw, but that’s a good thing. You have full control over the appearance of things.

When we say full control, we mean it. You can (and have to) build a menu on your own, but Tiptap will help you wire everything up.

Menus

The editor provides a fluent API to trigger commands and add active states. You can use any markup you like. To make the positioning of menus easier, Tiptap provides a few utilities and components. Let’s go through the most typical use cases one by one.

Fixed menu

A fixed menu is one that permanently sits in one location. For example, it's popular to place a fixed menu above the editor. Tiptap doesn't come prepackaged with a fixed menu, but you can build one by simply creating a <div> element and filling it with a few <button> elements. See below to learn how those buttons can trigger commands in the editor, for example bolding or italicizing text.

Bubble menu

A bubble menu is one that appears when selecting text. The markup and styling here is totally up to you.

Floating menu

A floating menu appears in the editor when you place your cursor on an empty line. Again, the markup and styling here is totally up to you.

Slash commands (work in progress)

Although there isn't an official extension yet, there is an experiment that allows you to use "slash commands." With slash commands, typing / at the beginning of a new line will reveal a popup menu.

Buttons

Okay, you’ve got your menu. But how do you wire things up?

Commands

You’ve got the editor running already and want to add your first button. You need a <button> HTML tag with a click handler. Depending on your setup, that can look like the following example:

<button onclick="editor.chain().focus().toggleBold().run()">Bold</button>

Oh, that’s a long command, right? Actually, it’s a chain of commands. Let’s go through this one by one:

editor.chain().focus().toggleBold().run()

1. editor should be a Tiptap instance,
2. chain() is used to tell the editor you want to execute multiple commands,
3. focus() sets the focus back to the editor,
4. toggleBold() marks the selected text bold, or removes the bold mark from the text selection if it’s already applied and
5. run() will execute the chain.

In other words: This will be a typical Bold button for your text editor.

Which commands are available depends on what extensions you have registered with the editor. Most extensions come with a set…(), unset…() and toggle…() command. Read the extension documentation to see what’s actually available or just surf through your code editor’s autocomplete.

Keep the focus

You have already seen the focus() command in the above example. When you click on the button, the browser focuses that DOM element and the editor loses focus. It’s likely you want to add focus() to all your menu buttons, so the writing flow of your users isn’t interrupted.

The active state

The editor provides an isActive() method to check if something is applied to the selected text already. In Vue.js you can toggle a CSS class with help of that function:

<button
  :class="{ 'is-active': editor.isActive('bold') }"
  @click="editor.chain().focus().toggleBold().run()"
>
  Bold
</button>

This toggles the .is-active class accordingly and works for nodes and marks. You can even check for specific attributes. Here is an example with the Highlight mark, that ignores different attributes:

editor.isActive('highlight')

And an example that compares the given attribute(s):

editor.isActive('highlight', { color: '#ffa8a8' })

There is even support for regular expressions:

editor.isActive('textStyle', { color: /.*/ })

You can even check nodes and marks, but check for the attributes only. Here is an example with the TextAlign extension:

editor.isActive({ textAlign: 'right' })

If your selection spans multiple nodes or marks, or only part of the selection has a mark, isActive() will return false and indicate nothing is active. This is how it is supposed to be, because it allows people to apply a new node or mark to that selection right-away.

User experience

When designing a great user experience you should consider a few things.

Accessibility

• Make sure users can navigate the menu with their keyboard
• Use proper title attributes
• Use proper aria attributes
• List available keyboard shortcuts

Icons

Most editor menus use icons for their buttons. In some of our demos, we use the open source icon set Remix Icon, which is free to use. But it’s totally up to you what you use. Here are a few icon sets you can consider:

• Remix Icon
• Font Awesome
• UI icons