Mention Trigger Button

A fully accessible mention trigger button for Tiptap editors. Easily insert mention triggers like "@" to initiate mention functionality with keyboard shortcut support and flexible customization options.

Installation

Add the component via the Tiptap CLI:

npx @tiptap/cli@latest add mention-trigger-button

Components

`<MentionTriggerButton />`

A prebuilt React component that inserts mention triggers into the editor.

Usage

function MyMentionTriggerButton() {
  return (
    <MentionTriggerButton
      editor={editor}
      text="Mention"
      trigger="@"
      hideWhenUnavailable={true}
      showShortcut={true}
      onTriggered={(trigger) => console.log('Inserted:', trigger)}
    />
  )
}

Props

Name	Type	Default	Description
`editor`	`Editor \| null`	`undefined`	The Tiptap editor instance
`node`	`Node \| null`	`undefined`	The node to apply trigger to
`nodePos`	`number \| null`	`undefined`	The position of the node in the document
`text`	`string`	`undefined`	Optional text label for the button
`trigger`	`string`	`"@"`	The trigger text to insert
`hideWhenUnavailable`	`boolean`	`false`	Hides the button when trigger insertion is not available
`onTriggered`	`(trigger: string) => void`	`undefined`	Callback fired after a successful trigger insertion
`showShortcut`	`boolean`	`false`	Shows a keyboard shortcut badge (if available)

Hooks

`useMentionTrigger()`

A custom hook to build your own mention trigger button with full control over rendering and behavior.

Usage

function MyMentionTriggerButton() {
  const { isVisible, canInsert, handleMention, label, shortcutKeys, trigger, Icon } =
    useMentionTrigger({
      editor: myEditor,
      trigger: '@',
      hideWhenUnavailable: true,
      onTriggered: (trigger) => console.log('Inserted:', trigger),
    })

  if (!isVisible) return null

  return (
    <button onClick={handleMention} disabled={!canInsert} aria-label={label}>
      <Icon />
      {label}
      {shortcutKeys && <Badge>{parseShortcutKeys({ shortcutKeys })}</Badge>}
    </button>
  )
}

Props

Name	Type	Default	Description
`editor`	`Editor \| null`	`undefined`	The Tiptap editor instance
`node`	`Node \| null`	`undefined`	The node to apply trigger to
`nodePos`	`number \| null`	`undefined`	The position of the node in the document
`trigger`	`string`	`"@"`	The trigger text to insert
`hideWhenUnavailable`	`boolean`	`false`	Hides the button if trigger insertion is not available
`onTriggered`	`(trigger: string) => void`	`undefined`	Callback fired after a successful trigger insertion

Return Values

Name	Type	Description
`isVisible`	`boolean`	Whether the button should be rendered
`canInsert`	`boolean`	If trigger insertion is currently allowed
`handleMention`	`() => boolean`	Function to insert the mention trigger
`label`	`string`	Accessible label text for the button
`shortcutKeys`	`string`	Keyboard shortcut (Cmd/Ctrl + Shift + 2)
`trigger`	`string`	The trigger text that will be inserted
`Icon`	`React.FC`	Icon component for the mention trigger button

Utilities

`canInsertMention(editor, node?, nodePos?)`

Checks if a mention trigger can be inserted in the current editor state or at a specific position.

import { canInsertMention } from '@/registry/tiptap-ui/mention-trigger-button'

const canInsert = canInsertMention(editor) // Check current position
const canInsertAtNode = canInsertMention(editor, node, nodePos) // Check specific position

`addMentionTrigger(editor, trigger?, node?, nodePos?)`

Programmatically inserts a mention trigger in the editor.

import { addMentionTrigger } from '@/registry/tiptap-ui/mention-trigger-button'

// Insert at current position
const success = addMentionTrigger(editor, '@')

// Insert at specific node/position
const success2 = addMentionTrigger(editor, '#', node, nodePos)

// Insert with custom trigger
const success3 = addMentionTrigger(editor, '/')

if (success) {
  console.log('Mention trigger inserted successfully!')
}

Keyboard Shortcuts

The mention trigger button supports the following keyboard shortcut:

Cmd/Ctrl + Shift + 2: Insert mention trigger

The shortcut is automatically registered when using either the <MentionTriggerButton /> component or the useMentionTrigger() hook.

Requirements

Dependencies

@tiptap/react - Core Tiptap React integration
@tiptap/extension-mention - Mention extension
react-hotkeys-hook - Keyboard shortcut management

Referenced Components

use-tiptap-editor (hook)
button (primitive)
badge (primitive)
tiptap-utils (lib)
at-sign-icon (icon)