Mention Trigger Button
Available in Start plan
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-buttonComponents
<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 '@/components/tiptap-ui/mention-trigger-button' const canInsert = canInsertMention(editor) // Check current position const canInsertAtNode = canInsertMention(editor, node, nodePos) // Check specific positionaddMentionTrigger(editor, trigger?, node?, nodePos?)
Programmatically inserts a mention trigger in the editor.
import { addMentionTrigger } from '@/components/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 extensionreact-hotkeys-hook- Keyboard shortcut management
Referenced Components
use-tiptap-editor(hook)button(primitive)badge(primitive)tiptap-utils(lib)at-sign-icon(icon)