# How to Add Custom Keyboard Shortcuts for Tiptap Editor Actions

> Learn how to add custom keyboard shortcuts for Tiptap editor actions using shortcutKeys and addKeyboardShortcuts in your extension configuration for seamless editing.

- Repository: [Hung Hoang/reactjs-tiptap-editor](https://github.com/hunghg255/reactjs-tiptap-editor)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/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`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/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`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/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`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/extensions/Bold/Bold.ts), the configuration updates the tooltip hint from the default `⌘+B` to `⌘+Shift+B`:

```tsx
// 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`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/extensions/Indent/Indent.ts) adds `Ctrl+Shift+I` (or `⌘+Shift+I` on macOS) to trigger indentation:

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

```tsx
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`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/components/ActionButton.tsx) renders the shortcut hint next to toolbar buttons:

```tsx
// 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`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/types.ts)** – Contains the `GeneralOptions` interface that defines the `shortcutKeys?: string[] | string[][]` type used by all extensions.
- **[`src/extensions/Bold/Bold.ts`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/extensions/Bold/Bold.ts)** – Demonstrates overriding `shortcutKeys` in `addOptions` to change UI hints.
- **[`src/extensions/Indent/Indent.ts`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/extensions/Indent/Indent.ts)** – Shows how to implement `addKeyboardShortcuts` for registering new key combinations.
- **[`src/components/ActionButton.tsx`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/components/ActionButton.tsx)** – Renders the shortcut text in toolbar buttons by reading `extension.options.shortcutKeys`.
- **[`docs/guide/toolbar.md`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/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`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/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`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/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.