---
title: "Mention Trigger Button"
description: "Insert mention trigger characters in Tiptap editors with smart positioning, customizable triggers, keyboard shortcuts, and accessibility support."
canonical_url: "https://tiptap.dev/docs/ui-components/components/mention-trigger-button"
---

# Mention Trigger Button

Insert mention trigger characters in Tiptap editors with smart positioning, customizable triggers, keyboard shortcuts, and accessibility support.

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.

> **Interactive demo:** [mention trigger button](https://template.tiptap.dev/preview/tiptap-ui/mention-trigger-button)

## Installation

Add the component via the Tiptap CLI:

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

## Components

### `<MentionTriggerButton />`

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

#### Usage

```tsx
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

```tsx
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.

```tsx
import { canInsertMention } from '@/components/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.

```tsx
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 extension
- `react-hotkeys-hook` - Keyboard shortcut management

### Referenced Components

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