How to Add Custom Keyboard Shortcuts for Tiptap Editor Actions

You can customize keyboard shortcuts in the reactjs-tiptap-editor by setting the shortcutKeys option for UI hints and implementing the addKeyboardShortcuts method for actual key bindings in your extension configuration.

The reactjs-tiptap-editor repository provides a React wrapper around Tiptap with built-in shortcut customization capabilities. Every extension can accept custom keyboard shortcuts through the GeneralOptions interface defined in src/types.ts, allowing you to override default key combinations or add entirely new ones without modifying core library code.

Understanding the Shortcut Architecture

The editor exposes two distinct mechanisms for keyboard customization. Knowing when to use each ensures your shortcuts appear correctly in the UI and respond to user input.

The shortcutKeys Option for UI Hints

The shortcutKeys property, defined in the GeneralOptions type in src/types.ts, controls the shortcut display in tooltips and menus. This option accepts a string array (string[]) or nested arrays (string[][]) for multiple shortcuts, but only updates the visual hint unless paired with actual keybinding logic.

The addKeyboardShortcuts Method for Command Binding

To make a shortcut functional, you must implement addKeyboardShortcuts inside your extension. This method returns an object mapping Tiptap key strings (like 'Mod-Shift-i' or 'Tab') to command functions. According to the source code in src/extensions/Indent/Indent.ts, this is where you register the actual keyboard listener.

Step-by-Step: Customizing Keyboard Shortcuts

Follow these steps to override default shortcuts or add custom key combinations to any Tiptap extension.

Step 1: Override UI Hints with shortcutKeys

Modify the extension's addOptions method to change the shortcut displayed in the toolbar. In src/extensions/Bold/Bold.ts, the configuration updates the tooltip hint from the default ⌘+B to ⌘+Shift+B:

// src/extensions/Bold/Bold.ts
export const Bold = TiptapBold.extend<BoldOptions>({
  addOptions() {
    return {
      ...this.parent?.(),
      // Override the default shortcut (⌘+B) with ⌘+Shift+B
      shortcutKeys: ['mod', 'Shift', 'B'],
      button: ({ editor, t, extension }) => ({
        component: ActionButton,
        componentProps: {
          action: () => editor.commands.toggleBold(),
          isActive: () => editor.isActive('bold'),
          icon: 'Bold',
          // The UI now shows the custom combo
          shortcutKeys: extension.options.shortcutKeys ?? ['mod', 'B'],
          tooltip: t('editor.bold.tooltip'),
        },
      }),
    };
  },
});

Step 2: Add New Key Bindings with addKeyboardShortcuts

For shortcuts that do not exist in the default configuration, implement addKeyboardShortcuts directly in the extension file. The following example from src/extensions/Indent/Indent.ts adds Ctrl+Shift+I (or ⌘+Shift+I on macOS) to trigger indentation:

// src/extensions/Indent/Indent.ts
addKeyboardShortcuts() {
  return {
    // Keep the default Tab/Shift-Tab and add a custom Ctrl+I for indent
    Tab: () => this.editor.commands.indent(),
    'Shift-Tab': () => this.editor.commands.outdent(),
    'Mod-Shift-i': () => this.editor.commands.indent(), // ← custom shortcut
  };
},

Step 3: Configure Extensions in Your Editor Instance

Pass your customized extensions to the useEditor hook. The configure method merges your shortcutKeys overrides with the extension's default options:

import { Bold } from '@/extensions/Bold';
import { Indent } from '@/extensions/Indent';
import { useEditor } from '@tiptap/react';

const extensions = [
  // Override Bold's shortcut
  Bold.configure({ shortcutKeys: ['mod', 'Shift', 'B'] }),

  // Override Indent's shortcuts (adds Ctrl+I)
  Indent.configure({
    shortcutKeys: [['Tab'], ['Shift', 'Tab']],
    // custom key binding is already inside the extension file
  }),
  // ...other extensions
];

const editor = useEditor({
  extensions,
});

Step 4: Verify the UI Display

The ActionButton component in src/components/ActionButton.tsx renders the shortcut hint next to toolbar buttons:

// src/components/ActionButton.tsx (excerpt)
{shortcutKeys?.length && (
  <span>{getShortcutKeys(shortcutKeys)}</span>
)}

Hover over the Bold button in your editor to confirm the custom ⌘ Shift B label appears, validating that the shortcutKeys option propagated correctly from your configuration to the UI.

Key Implementation Files

Understanding these source files helps you navigate the codebase when implementing custom shortcuts:

• src/types.ts – Contains the GeneralOptions interface that defines the shortcutKeys?: string[] | string[][] type used by all extensions.
• src/extensions/Bold/Bold.ts – Demonstrates overriding shortcutKeys in addOptions to change UI hints.
• src/extensions/Indent/Indent.ts – Shows how to implement addKeyboardShortcuts for registering new key combinations.
• src/components/ActionButton.tsx – Renders the shortcut text in toolbar buttons by reading extension.options.shortcutKeys.
• docs/guide/toolbar.md – Provides usage examples for configuring the editor with custom extensions.

Summary

• Use shortcutKeys in addOptions to change the shortcut hint displayed in toolbar tooltips.
• Use addKeyboardShortcuts to register the actual keybinding that triggers editor commands.
• Both mechanisms are required if you want the UI to match the functionality: shortcutKeys for display, addKeyboardShortcuts for behavior.
• Configure extensions using .configure({ shortcutKeys: [...] }) when instantiating the editor with useEditor.
• Reference src/types.ts to understand the type definition available to all extensions in the repository.

Frequently Asked Questions

What is the difference between shortcutKeys and addKeyboardShortcuts?

The shortcutKeys option only changes the visual hint displayed in the toolbar tooltip, while addKeyboardShortcuts actually registers the key listener with the editor. If you update shortcutKeys without implementing addKeyboardShortcuts, the UI will display the new shortcut but pressing those keys will not trigger any action.

Can I add multiple keyboard shortcuts for the same action?

Yes, you can define multiple shortcuts by passing a nested array to shortcutKeys like [['mod', 'B'], ['mod', 'Shift', 'B']]. In addKeyboardShortcuts, simply return multiple entries pointing to the same command function, such as {'Mod-b': () => command(), 'Mod-B': () => command()}.

How do I remove a default keyboard shortcut?

To disable a default shortcut, override addKeyboardShortcuts in your extension and return an object that omits the key you want to remove, or explicitly map it to a function that returns false to prevent propagation. You should also update shortcutKeys to remove the hint from the UI.

Where are shortcut hints displayed in the reactjs-tiptap-editor interface?

Shortcut hints appear in the toolbar tooltips next to action buttons. The ActionButton component in src/components/ActionButton.tsx reads the shortcutKeys from the extension options and renders them using the getShortcutKeys utility, making the keyboard combinations visible when users hover over buttons.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}