Mention extension

Honestly, the mention node is amazing. It adds support for @mentions, for example to ping users, and provides full control over the rendering.

Literally everything can be customized. You can pass a custom component for the rendering. All examples use .filter() to search through items, but feel free to send async queries to an API or add a more advanced library like fuse.js to your project.

Install

npm install @tiptap/extension-mention

Dependencies

Since 2.0.0-beta.193 we marked the @tiptap/suggestion as a peer dependency. That means, you will need to install it manually.

npm install @tiptap/suggestion

Settings

HTMLAttributes

Custom HTML attributes that should be added to the rendered HTML tag.

Mention.configure({
  HTMLAttributes: {
    class: 'my-custom-class',
  },
})

renderText

Define how a mention text should be rendered.

Mention.configure({
  renderText({ options, node }) {
    return `${options.suggestion.char}${node.attrs.label ?? node.attrs.id}`
  },
})

renderHTML

Define how a mention html element should be rendered, this is useful if you want to render an element other than span (e.g a)

Mention.configure({
  renderHTML({ options, node }) {
    return [
      'a',
      mergeAttributes({ href: '/profile/1' }, options.HTMLAttributes),
      `${options.suggestion.char}${node.attrs.label ?? node.attrs.id}`,
    ]
  },
})

deleteTriggerWithBackspace

Toggle whether the suggestion character(s) should also be deleted on deletion of a mention node. Default is false.

Mention.configure({
  deleteTriggerWithBackspace: true,
})

suggestion

Options for the Suggestion utility. Used to define what character triggers the suggestion popup, among other parameters. Read more.

Mention.configure({
  suggestion: {
    // …
  },
})

suggestions

Allows you to define multiple types of mentions within the same editor. For example, define a mention for people with the @ trigger and one for movies with the # trigger. Read more about the Suggestion utility.

Mention.configure({
  suggestions: [
    {
      char: '@',
      // Other options of the Suggestion utility
    },
    {
      char: '#',
      // Other options of the Suggestion utility
    },
  ],
})

Below is an example demo:

Collaboration

When working with Tiptap Collaboration, suggestions can sometimes "pop open" for remote users when someone else is typing a mention. To prevent this, you can configure the shouldShow option:

import { Mention } from '@tiptap/extension-mention'
import { isChangeOrigin } from '@tiptap/extension-collaboration'

const Editor = new Editor({
  extensions: [
    Mention.configure({
      suggestion: {
        shouldShow: ({ transaction }) => isChangeOrigin(transaction),
      },
    }),
  ],
})

This ensures that the suggestion menu only opens for the user who actually typed the trigger character.

Source code

packages/extension-mention/