---
title: "FloatingMenu extension"
description: "Use the Floating Menu extension in Tiptap to add a menu that appears on empty lines. Learn more in the docs."
canonical_url: "https://tiptap.dev/docs/editor/extensions/functionality/floatingmenu"
---

# FloatingMenu extension

Use the Floating Menu extension in Tiptap to add a menu that appears on empty lines. Learn more in the docs.

Use the Floating Menu extension in Tiptap to make a menu appear on an empty line.

> **Interactive demo:** [FloatingMenu](https://embed.tiptap.dev/preview/Extensions/FloatingMenu)

> **Warning:**
>
> If you are using a framework like React or Vue, use the frameworks specific `FloatingMenu` component instead of the extension. The component provides a more convenient API and handles the DOM element for you. You can find more information about the component in the [Usage with frameworks](#usage-with-frameworks) section below.

## Install the extension

Install the Floating Menu extension and the [Floating UI](https://floating-ui.com) library.

```bash
npm install @tiptap/extension-floating-menu @floating-ui/dom@^1.6.0
```

## Settings

### element

The DOM element that contains your menu.

Type: `HTMLElement`

Default: `null`

### updateDelay

The `FloatingMenu` debounces the `update` method to allow the floating menu to not be updated on every selection update. This can be controlled in milliseconds.
The `FloatingMenuPlugin` will come with a default delay of 250ms. This can be deactivated, by setting the delay to `0` which deactivates the debounce.

Type: `Number`

Default: `250`

### resizeDelay

The `FloatingMenu` debounces the resize and scroll event handlers to allow the floating menu to not be updated on every resize or scroll event. This can be controlled in milliseconds.

Type: `Number`

Default: `60`

### appendTo

The element to which the floating menu should be appended to in the DOM. Can be a `HTMLElement` or a callback function that returns a `HTMLElement`.

Type: `HTMLElement | (() => HTMLElement) | undefined`

Default: `undefined`, the menu will be appended to `document.body`.

### options

Under the hood, the `FloatingMenu` uses [Floating UI](https://floating-ui.com). You can control the middleware and positioning of the floating menu with these options.

Type: `Object`

Default: `{ strategy: 'absolute', placement: 'right' }`

| Option          | Type                                   | Description                                                                                                                                                  |
| --------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `strategy`      | `string`                               | The positioning strategy. See [here](https://floating-ui.com/docs/computePosition#strategy)                                                                  |
| `placement`     | `string`                               | The placement of the menu. See [here](https://floating-ui.com/docs/computePosition#placement)                                                                |
| `offset`        | `number`, `OffsetOptions` or `boolean` | The [offset middleware options](https://floating-ui.com/docs/offset#options). If `true` use default options, if `false` disable the middleware               |
| `flip`          | `FlipOptions` or `boolean`             | The [flip middleware options](https://floating-ui.com/docs/flip#options). If `true` use default options, if `false` disable the middleware                   |
| `shift`         | `ShiftOptions` or `boolean`            | The [shift middleware options](https://floating-ui.com/docs/shift#options). If `true` use default options, if `false` disable the middleware                 |
| `arrow`         | `ArrowOptions` or `false`              | The [arrow middleware options](https://floating-ui.com/docs/arrow#options). If `false` disable the middleware                                                |
| `size`          | `SizeOptions` or `boolean`             | The [size middleware options](https://floating-ui.com/docs/size#options). If `true` use default options, if `false` disable the middleware                   |
| `autoPlacement` | `AutoPlacementOptions` or `boolean`    | The [autoPlacement middleware options](https://floating-ui.com/docs/autoPlacement#options). If `true` use default options, if `false` disable the middleware |
| `hide`          | `HideOptions` or `boolean`             | The [hide middleware options](https://floating-ui.com/docs/hide#options). If `true` use default options, if `false` disable the middleware                   |
| `inline`        | `InlineOptions` or `boolean`           | The [inline middleware options](https://floating-ui.com/docs/inline#options). If `true` use default options, if `false` disable the middleware               |
| `onShow`        | `Function` or `undefined`              | A callback that is called when the menu is shown. This can be used to add custom logic or styles when the menu is displayed.                                 |
| `onHide`        | `Function` or `undefined`              | A callback that is called when the menu is hidden. This can be used to add custom logic or styles when the menu is hidden.                                   |
| `onUpdate`      | `Function` or `undefined`              | A callback that is called when the menu is updated. This can be used to add custom logic or styles when the menu is updated.                                 |
| `onDestroy`     | `Function` or `undefined`              | A callback that is called when the menu is destroyed. This can be used to add custom logic or styles when the menu is removed.                               |

### pluginKey

The key for the underlying ProseMirror plugin. Make sure to use different keys if you add more than one instance.

Type: `string | PluginKey`

Default: `'floatingMenu'`

### shouldShow

A callback to control whether the menu should be shown or not.

Type: `(props) => boolean`

## Source code

[packages/extension-floating-menu/](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-floating-menu/)

## Use in Vanilla JavaScript

```js
import { Editor } from '@tiptap/core'
import FloatingMenu from '@tiptap/extension-floating-menu'

new Editor({
  element: document.querySelector('#editor'),
  extensions: [
    StarterKit,
    FloatingMenu.configure({
      element: document.querySelector('#floating-menu'),
    }),
  ],
  content: '<p>Click on an empty line to see the floating menu.</p>',
})
```

Add a menu element to your HTML:

```html
<div id="floating-menu" style="display: none; position: absolute;">
  <button onclick="editor.chain().focus().toggleHeading({ level: 1 }).run()">H1</button>
  <button onclick="editor.chain().focus().toggleBulletList().run()">List</button>
</div>
<div id="editor"></div>
```

Tiptap will automatically show and position the menu element when the cursor is on an empty line.

## Usage with frameworks

### React

The `@tiptap/react` package comes with a `FloatingMenu` component you can import from `@tiptap/react/menus`. It provides the same functionality as the extension but with a React-friendly API. When using this component, you don't need to add the `FloatingMenu` extension to your editor.

```jsx
import { FloatingMenu } from '@tiptap/react/menus'

function MyFloatingMenu({ editor }) {
  return (
    <FloatingMenu editor={editor}>
      <button onClick={() => editor.chain().focus().setHeading({ level: 1 }).run()}>
        H1
      </button>
      <button onClick={() => editor.chain().focus().setBulletList().run()}>
        List
      </button>
    </FloatingMenu>
  )
}
```

### Vue

The `@tiptap/vue-3` package comes with a `FloatingMenu` component you can import from `@tiptap/vue-3/menus`. It provides the same functionality as the extension but with a Vue-friendly API. When using this component, you don't need to add the `FloatingMenu` extension to your editor.

```vue
<template>
  <FloatingMenu :editor="editor">
    <button @click="editor.chain().focus().setHeading({ level: 1 }).run()">
      H1
    </button>
    <button @click="editor.chain().focus().setBulletList().run()">
      List
    </button>
  </FloatingMenu>
</template>

<script setup>
  import { FloatingMenu } from '@tiptap/vue-3/menus'

  // make sure to pass the editor instance as a prop to the FloatingMenu component
  const { editor } = defineProps({
    editor: {
      type: Object,
      required: true,
    },
  })
</script>
```

**Note**: The same menu is also available in the Vue 2 version of Tiptap, you can import it from `@tiptap/vue-2/menus`.

### Custom logic

Customize the logic for showing the menu with the `shouldShow` option. For components, `shouldShow` can be passed as a prop.

```js
FloatingMenu.configure({
  shouldShow: ({ editor, view, state, oldState }) => {
    // show the floating within any paragraph
    return editor.isActive('paragraph')
  },
})
```

### Multiple menus

Use multiple menus by setting an unique `pluginKey`.

```js
import { Editor } from '@tiptap/core'
import FloatingMenu from '@tiptap/extension-floating-menu'

new Editor({
  extensions: [
    FloatingMenu.configure({
      pluginKey: 'floatingMenuOne',
      element: document.querySelector('.menu-one'),
    }),
    FloatingMenu.configure({
      pluginKey: 'floatingMenuTwo',
      element: document.querySelector('.menu-two'),
    }),
  ],
})
```

Alternatively you can pass a ProseMirror `PluginKey`.

```js
import { Editor } from '@tiptap/core'
import FloatingMenu from '@tiptap/extension-floating-menu'
import { PluginKey } from '@tiptap/pm/state'

new Editor({
  extensions: [
    FloatingMenu.configure({
      pluginKey: new PluginKey('floatingMenuOne'),
      element: document.querySelector('.menu-one'),
    }),
    FloatingMenu.configure({
      pluginKey: new PluginKey('floatingMenuOne'),
      element: document.querySelector('.menu-two'),
    }),
  ],
})
```

### Force update the position of the floating menu

If the floating menu changes size after the initial render, its position will not be adjusted automatically. To fix this, you can force update the position by setting a `pluginKey` on the extension and emitting an `'updatePosition'` event with that key.

```ts
FloatingMenu.configure({
  pluginKey: 'myFloatingMenu',
  element: document.querySelector('.menu'),
})

editor.commands.setMeta('myFloatingMenu', 'updatePosition')
```

To target a specific floating menu, emit an `'updatePosition'` event via transaction metadata and use that menu's `pluginKey`:

```ts
FloatingMenu.configure({
  pluginKey: 'myFloatingMenu',
  element: document.querySelector('.menu'),
})
```

For example, if you have multiple floating menus:

```ts
editor.commands.setMeta('floatingMenuOne', 'updatePosition')
```

If you use the React or Vue `FloatingMenu` component and want to trigger `updatePosition` externally, pass an explicit `pluginKey` prop to the component first. If you omit `pluginKey`, the component creates its own ProseMirror `PluginKey`, which external code cannot reliably reference later.

### Programmatically show or hide the floating menu

You can programmatically show or hide the floating menu by setting a `pluginKey` on the extension and dispatching a transaction with the `'show'` or `'hide'` meta value using that key.

```ts
// Show the floating menu
editor.commands.setMeta('myFloatingMenu', 'show')

// Hide the floating menu
editor.commands.setMeta('myFloatingMenu', 'hide')
```

**Note:** dispatching `'show'` or `'hide'` will override the behavior defined in `shouldShow`.