> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Context menu

The built-in right-click menu. Shows relevant actions based on cursor position and document state. Configure it via `modules.contextMenu`, or disable it and render your own.

> [!NOTE]
>
> Building a fully custom right-click menu? See [Custom right-click menu](https://docs.superdoc.dev/editor/custom-ui/context-menu.md) for the controller-driven flow: `ui.viewport.contextAt({ x, y })` returns one bundle, registrations contribute items via `register({ contextMenu: { when } })`, and `item.invoke()` dispatches with the bundle bound. The page below covers the built-in module only.

## Quick start

The built-in menu is **enabled by default**. Right-click anywhere in the document to open it.

To turn off the built-in menu, set `disableContextMenu: true`. This switches off SuperDoc's own menu and lets the browser's native right-click menu (Copy / Paste / Inspect) appear, or lets your own custom `contextmenu` listener take over:

```javascript theme={null}
new SuperDoc({
  selector: '#editor',
  disableContextMenu: true
});
```

## Configuration

```javascript theme={null}
new SuperDoc({
  selector: '#editor',
  modules: {
    contextMenu: {
      includeDefaultItems: true,
      customItems: [],
      menuProvider: null
    }
  }
});
```

**disableContextMenu** `boolean` (default: false)

Top-level option that disables the built-in menu and lets the browser's native right-click menu (or your own custom `contextmenu` listener) appear instead. Pair with the [custom right-click menu](https://docs.superdoc.dev/editor/custom-ui/context-menu.md) flow when you're rendering your own.

**modules.contextMenu.includeDefaultItems** `boolean` (default: true)

Whether to include the built-in menu items

**modules.contextMenu.customItems** `Array` (default: \[])

Custom menu sections to add or merge. See [Custom Items](#custom-items).

**modules.contextMenu.menuProvider** `function`

Advanced: function to fully control menu contents. See [Menu Provider](#menu-provider).

## Default items

Items shown depend on document context.

### Right-click

| Item | Section | Condition |
| - | - | - |
| Accept change | `track-changes` | On a tracked change |
| Reject change | `track-changes` | On a tracked change |
| Replacement actions | `proofing` | One direct menu item per provider suggestion on a spelling issue |
| Ignore | `proofing` | On a spelling issue when `proofing.allowIgnoreWord` is enabled |
| Insert link | `general` | Always |
| Insert table | `general` | Not inside a table |
| Edit table | `general` | Inside a table |
| Cut | `clipboard` | Text selected |
| Copy | `clipboard` | Text selected |
| Paste | `clipboard` | Always |

> [!NOTE]
>
> Spell-check items appear automatically when top-level [proofing](https://docs.superdoc.dev/editor/superdoc/configuration.md#proofing) is enabled and the clicked text has a spelling issue. Suggestion items come from the provider's `replacements` array.

## Custom items

Add custom items by defining sections in `customItems`. Each section has an `id` and an array of `items`.

```javascript theme={null}
modules: {
  contextMenu: {
    customItems: [{
      id: 'my-actions',
      items: [
        {
          id: 'insert-signature',
          label: 'Insert Signature',
          icon: '<svg>...</svg>',
          action: (editor, context) => {
            editor.commands.insertContent('- Signed');
          },
          showWhen: (context) => {
            return context.trigger === 'click';
          }
        }
      ]
    }]
  }
}
```

### Item properties

**id** `string` *required*

Unique identifier for the item

**label** `string` *required*

Display text shown in the menu

**icon** `string`

SVG string for the item icon

**action** `function`

Handler called when the item is clicked. Receives `(editor, context)`.

**component** `Component`

Vue component to render as a popover when the item is selected (e.g., a table grid picker)

**showWhen** `function`

Function that receives the [context object](#context-object) and returns `boolean`. Items without `showWhen` are always visible.

**render** `function`

Custom render function for the menu item. Receives the context and should return an `HTMLElement`.

### Merging with default sections

If a custom section has the same `id` as a default section, the items are merged:

```javascript theme={null}
modules: {
  contextMenu: {
    customItems: [{
      // Adds items to the existing 'general' section
      id: 'general',
      items: [{
        id: 'insert-divider',
        label: 'Insert Divider',
        action: (editor) => {
          editor.commands.setHorizontalRule();
        }
      }]
    }]
  }
}
```

## Menu provider

For full control over menu contents, use `menuProvider`. It receives the context and the computed sections array, and should return a new sections array.

```javascript theme={null}
modules: {
  contextMenu: {
    menuProvider: (context, sections) => {
      // Filter out clipboard section in editing mode
      if (context.documentMode === 'editing') {
        return sections.filter(s => s.id !== 'clipboard');
      }
      return sections;
    }
  }
}
```

> [!WARNING]
>
> `menuProvider` runs after default items and `customItems` are merged. If it returns `null` or `undefined`, the original sections are used.

## Context object

Both `showWhen` and `menuProvider` receive a context object with the current editor state:

| Property | Type | Description |
| - | - | - |
| `trigger` | `'click'` | How the menu was opened |
| `editor` | `Object` | The editor instance |
| `selectedText` | `string` | Currently selected text |
| `hasSelection` | `boolean` | Whether text is selected |
| `selectionStart` | `number` | Selection start position |
| `selectionEnd` | `number` | Selection end position |
| `isInTable` | `boolean` | Cursor is inside a table |
| `isInList` | `boolean` | Cursor is inside a list |
| `isTrackedChange` | `boolean` | Cursor is on a tracked change |
| `trackedChangeId` | `string \| null` | ID of the tracked change at cursor |
| `documentMode` | `string` | Current mode (`'editing'`, `'viewing'`, `'suggesting'`) |
| `currentNodeType` | `string \| null` | Type name of the node at cursor |
| `activeMarks` | `string[]` | Active mark type names at cursor |
| `isEditable` | `boolean` | Whether the editor is editable |
| `clipboardContent` | `Object` | Clipboard state info |
| `pos` | `number \| null` | Document position |
| `node` | `Object \| null` | Node at cursor position |

## Keyboard navigation

When the menu is open:

| Key | Action |
| - | - |
| `Arrow Down` | Move to next item |
| `Arrow Up` | Move to previous item |
| `Enter` | Execute selected item |
| `Escape` | Close menu |
| Type any text | Filter items by label |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.