Emoji Trigger Button

A fully accessible emoji trigger button for Tiptap editors. Insert emoji trigger characters to activate emoji selection with keyboard shortcut support and flexible positioning options.

Installation

Add the component via the Tiptap CLI:

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

Components

`<EmojiTriggerButton />`

A prebuilt React component that inserts emoji trigger characters in the editor.

Usage

export default function MyEditor() {
  return (
    <EmojiTriggerButton
      editor={editor}
      text="Emoji"
      trigger="::"
      hideWhenUnavailable={true}
      showShortcut={true}
      onTriggerApplied={(trigger) => console.log(`Trigger applied: ${trigger}`)}
    />
  )
}

Props

Name	Type	Default	Description
`editor`	`Editor \| null`	`undefined`	The Tiptap editor instance
`node`	`Node \| null`	`undefined`	Optional node to insert trigger after
`nodePos`	`number \| null`	`undefined`	Optional position of the node to insert trigger after
`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
`onTriggerApplied`	`(trigger: string) => void`	`undefined`	Callback fired after a successful trigger insertion
`showShortcut`	`boolean`	`false`	Shows a keyboard shortcut badge (if available)

Hooks

`useEmojiTrigger()`

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

Usage

function MyEmojiTriggerButton() {
  const { isVisible, handleAddTrigger, canAddTrigger, label, shortcutKeys, trigger, Icon } =
    useEmojiTrigger({
      editor: myEditor,
      trigger: '::',
      hideWhenUnavailable: true,
      onTriggerApplied: (trigger) => console.log(`Applied: ${trigger}`),
    })

  if (!isVisible) return null

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

Props

Name	Type	Default	Description
`editor`	`Editor \| null`	`undefined`	The Tiptap editor instance
`node`	`Node \| null`	`undefined`	Optional node to insert trigger after
`nodePos`	`number \| null`	`undefined`	Optional position of the node to insert trigger after
`trigger`	`string`	`":"`	The trigger text to insert
`hideWhenUnavailable`	`boolean`	`false`	Hides the button if trigger cannot be inserted
`onTriggerApplied`	`(trigger: string) => void`	`undefined`	Callback fired after successful trigger insertion

Return Values

Name	Type	Description
`isVisible`	`boolean`	Whether the button should be rendered
`canAddTrigger`	`boolean`	If the emoji trigger can be inserted
`handleAddTrigger`	`() => boolean`	Function to insert the emoji trigger
`label`	`string`	Accessible label text for the button
`shortcutKeys`	`string`	Keyboard shortcut (Cmd/Ctrl + Shift + E)
`trigger`	`string`	The current trigger text
`Icon`	`React.FC`	Icon component for the emoji trigger button (SmilePlusIcon)

Utilities

`canAddEmojiTrigger(editor)`

Checks if an emoji trigger can be inserted in the current editor state.

import { canAddEmojiTrigger } from '@/registry/tiptap-ui/emoji-trigger-button'

const canAdd = canAddEmojiTrigger(editor)

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

Programmatically inserts an emoji trigger at the current selection or specified position.

import { addEmojiTrigger } from '@/registry/tiptap-ui/emoji-trigger-button'

const success = addEmojiTrigger(editor, ':') // Insert at cursor
const successAtNode = addEmojiTrigger(editor, '::', node, nodePos) // Insert at node

Keyboard Shortcuts

The emoji trigger button supports the following keyboard shortcut:

Cmd/Ctrl + Shift + E: Insert emoji trigger at cursor position

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

Requirements

Dependencies

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

Referenced Components

use-tiptap-editor (hook)
button (primitive)
badge (primitive)
tiptap-utils (lib)
smile-plus-icon (icon)