tiptap/docs/guide/menus.md

116 lines
5.4 KiB
Markdown
Raw Normal View History

---
tableOfContents: true
---
2021-04-03 21:21:30 +08:00
# Create menus
## Introduction
2022-11-08 04:41:00 +08:00
Tiptap comes very raw, but thats a good thing. You have full control about the appearance of it.
2021-08-31 05:55:43 +08:00
When we say full control, we mean it. You can (and have to) build a menu on your own. We help you to wire everything up.
2021-04-03 21:21:30 +08:00
## Menus
2021-08-31 05:55:43 +08:00
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, we provide a few utilities and components. Lets go through the most typical use cases one by one.
2021-04-03 21:21:30 +08:00
### Fixed menu
2022-11-08 04:41:00 +08:00
A fixed menu, for example on top of the editor, can be anything. We dont provide such menu. Just add a `<div>` with a few `<button>`s. How those buttons can trigger [commands](/api/commands) is [explained below](#buttons).
2021-04-03 21:21:30 +08:00
### Bubble menu
The [bubble menu](/api/extensions/bubble-menu) appears when selecting text. Markup and styling is totally up to you.
2021-10-19 00:01:47 +08:00
https://embed.tiptap.dev/preview/Extensions/BubbleMenu?hideSource
2021-04-03 21:21:30 +08:00
### Floating menu
The [floating menu](/api/extensions/floating-menu) appears in empty lines. Markup and styling is totally up to you.
2021-10-19 00:01:47 +08:00
https://embed.tiptap.dev/preview/Extensions/FloatingMenu?hideSource
2021-04-03 21:21:30 +08:00
2021-04-09 05:00:01 +08:00
### Slash commands (work in progress)
2021-08-31 05:55:43 +08:00
Its not an official extension yet, but [theres an experiment you can use to add what we call slash commands](/experiments/commands). It allows you to start a new line with `/` and will bring up a popup to select which node should be added.
2021-04-09 05:00:01 +08:00
2021-04-03 21:21:30 +08:00
## Buttons
Okay, youve got your menu. But how do you wire things up?
2021-08-31 05:55:43 +08:00
2021-04-03 21:21:30 +08:00
### Commands
2021-08-31 05:55:43 +08:00
Youve 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:
2021-04-03 21:21:30 +08:00
```html
2021-10-26 22:23:48 +08:00
<button onclick="editor.chain().focus().toggleBold().run()">
2021-04-03 21:21:30 +08:00
Bold
</button>
```
2021-08-31 05:55:43 +08:00
Oh, thats a long command, right? Actually, its a [chain of commands](/api/commands#chain-commands). Lets go through this one by one:
2021-04-03 21:21:30 +08:00
```js
2021-04-07 05:36:07 +08:00
editor.chain().focus().toggleBold().run()
2021-04-03 21:21:30 +08:00
```
2021-10-20 04:30:45 +08:00
1. `editor` should be a Tiptap instance,
2021-04-03 21:21:30 +08:00
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 its 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 whats actually available or just surf through your code editors autocomplete.
### Keep the focus
2021-08-31 05:55:43 +08:00
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. Its likely you want to add `focus()` to all your menu buttons, so the writing flow of your users isnt interrupted.
2021-04-03 21:21:30 +08:00
### 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:
2021-04-03 21:21:30 +08:00
```html
2021-10-26 22:23:48 +08:00
<button :class="{ 'is-active': editor.isActive('bold') }" @click="editor.chain().focus().toggleBold().run()">
2021-04-03 21:21:30 +08:00
Bold
</button>
```
2021-08-31 05:55:43 +08:00
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`](/api/marks/highlight) mark, that ignores different attributes:
2021-04-03 21:21:30 +08:00
```js
editor.isActive('highlight')
```
And an example that compares the given attribute(s):
```js
editor.isActive('highlight', { color: '#ffa8a8' })
```
2021-08-31 05:55:43 +08:00
There is even support for regular expressions:
2021-08-20 17:11:41 +08:00
```js
editor.isActive('textStyle', { color: /.*/ })
```
2022-12-07 07:47:18 +08:00
You can even check nodes and marks, but check for the attributes only. Here is an example with the [`TextAlign`](/api/extensions/text-align) extension:
2021-04-03 21:21:30 +08:00
```js
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](https://developer.mozilla.org/de/docs/Web/HTML/Global_attributes/title)
* Use proper [aria attributes](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/WAI-ARIA_basics)
* List available keyboard shortcuts
:::warning Incomplete
2021-04-21 21:31:11 +08:00
This section needs some work. Do you know what else needs to be taken into account when building an editor menu? Let us know on [GitHub](https://github.com/ueberdosis/tiptap) or send us an email to [humans@tiptap.dev](mailto:humans@tiptap.dev)!
2021-04-03 21:21:30 +08:00
:::
### Icons
2021-08-31 05:55:43 +08:00
Most editor menus use icons for their buttons. In some of our demos, we use the open source icon set [Remix Icon](https://remixicon.com/), which is free to use. But its totally up to you what you use. Here are a few icon sets you can consider:
2021-04-03 21:21:30 +08:00
* [Remix Icon](https://remixicon.com/#editor)
* [Font Awesome](https://fontawesome.com/icons?c=editors)
* [UI icons](https://www.ibm.com/design/language/iconography/ui-icons/library/)