# Configure the context menu

> Add application actions or open SuperDoc's document-aware menu from your interface.



SuperDoc opens its document-aware menu when a user right-clicks or types `/` after whitespace. You can add application
actions, change the slash trigger, or open the menu from your interface.

## Try the context menu [#try-the-context-menu]

Expand the Editor, then select “Select this sentence, then right-click it to open the document menu.”

1. With **Add action** selected, right-click the selection and choose **Send selection to workflow**.
2. Confirm that the line below the Editor reports the selection.
3. Choose **Default** and right-click the selection again. SuperDoc's actions remain, but the application action is gone.

> **Interactive editor: Try the context menu**
>
> Sample: [open the fixture](/fixtures/context-menu-sample.docx).
>
> Preset: `context-menu`.
>
> Context-menu configurations available in the interactive Editor:
>
> - **Menu — `ui.contextMenu`:** choose **Default** or **Add action**. Add action keeps SuperDoc’s menu items and appends **Send selection to workflow** when you right-click selected text.
>
> Changing the menu configuration recreates the Editor from its current DOCX. Document edits remain; transient selection and menu state reset.
>
> Local DOCX selection: disabled.


Changing `ui.contextMenu` recreates the Editor from its current DOCX. Document edits remain, while the selection and
open menu reset.

## Add an application action [#add-an-application-action]

Continue with `/sample.docx` from the [Quickstart](/editor/quickstart). Append an action that appears only when the user
right-clicks selected text:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc, type ContextMenuConfig } from 'superdoc';
import 'superdoc/style.css';

const contextMenu = {
  sections: [
    {
      id: 'application-actions',
      items: [
        {
          id: 'send-selection-to-workflow',
          label: 'Send selection to workflow',
          showWhen: ({ hasSelection, trigger }) => trigger === 'click' && hasSelection,
          onSelect: async ({ context }) => {
            const selectedText = (await context?.selectedTextSettled)?.trim();
            if (selectedText) console.log('Workflow selection:', selectedText);
          },
        },
      ],
    },
  ],
} satisfies ContextMenuConfig;

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  ui: { contextMenu },
});

window.addEventListener('beforeunload', () => superdoc.destroy());

```

**React — `src/App.tsx`**

```tsx
import { SuperDocEditor, type ContextMenuConfig, type SuperDocEditorProps } from '@superdoc/react';
import '@superdoc/react/style.css';

const contextMenu = {
  sections: [
    {
      id: 'application-actions',
      items: [
        {
          id: 'send-selection-to-workflow',
          label: 'Send selection to workflow',
          showWhen: ({ hasSelection, trigger }) => trigger === 'click' && hasSelection,
          onSelect: async ({ context }) => {
            const selectedText = (await context?.selectedTextSettled)?.trim();
            if (selectedText) console.log('Workflow selection:', selectedText);
          },
        },
      ],
    },
  ],
} satisfies ContextMenuConfig;

const editorConfig = {
  ui: { contextMenu },
} satisfies Pick<SuperDocEditorProps, 'ui'>;

export default function App() {
  return <SuperDocEditor document='/sample.docx' ui={editorConfig.ui} />;
}

```


Vanilla also needs an Editor mount:

```html
<div id="editor"></div>

<script type="module" src="/src/main.ts"></script>

```

`showWhen()` receives the document context captured when the menu opens. The example requires a right-click and an
expanded selection, so the action stays hidden after `/`, a programmatic `open()`, or a collapsed caret.

`onSelect()` runs after the menu closes. Await `context.selectedTextSettled` when the action needs the final selection
text. Use `context.selectedText` synchronously when the action must preserve user activation for a clipboard call,
`window.open()`, or a file picker.

## Configure the menu [#configure-the-menu]

Choose a group, then choose a field. Each entry shows its generated TypeScript signature and a configuration fragment
you can copy.

### Opening

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `openOnSlash` | `boolean` | `true` | Optional | Choose whether typing `/` after whitespace opens the built-in menu. | Whether typing `/` after whitespace opens the menu (default: true). | — |

### Items

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `sections` | `readonly ContextMenuSection[]` | `undefined` | Optional | Append application actions or merge them into a section with the same ID. | Application sections appended to the menu, or merged into a built-in section with the same ID. | — |
| `defaultItems` | `boolean` | `true` | Optional | Choose whether SuperDoc's built-in actions appear with your sections. | Whether to include SuperDoc's built-in items (default: true). | — |

### Advanced

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `menuProvider` | `(context: ContextMenuOpenContext, sections: readonly ContextMenuResolvedSection[]) => readonly ContextMenuResolvedSection[] \| null \| undefined` | `undefined` | Optional | Filter or reorder the resolved sections before the menu renders. | Filter or reorder the resolved sections before they render. Return `null` or `undefined` to keep the original list. | — |


Use `showWhen()` on an item for ordinary context checks. Reserve `menuProvider()` for changes that need the complete
resolved section list.

## Open the menu from your application [#open-the-menu-from-your-application]

Set `openOnSlash: false` when your application owns the keyboard shortcut. Right-click still works. A button, shortcut,
or other control can call `superdoc.ui.contextMenu.open()` at the current selection or caret:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  ui: {
    contextMenu: { openOnSlash: false },
  },
});

document.querySelector('#open-context-menu')?.addEventListener('click', () => {
  const result = superdoc.ui.contextMenu.open();
  if (!result.ok) console.warn(`Context menu did not open: ${result.reason}`);
});

window.addEventListener('beforeunload', () => superdoc.destroy());

```

**React — `src/App.tsx`**

```tsx
import { useRef, useState } from 'react';
import { SuperDocEditor, type ContextMenuConfig, type SuperDocRef } from '@superdoc/react';
import '@superdoc/react/style.css';

const contextMenu = {
  openOnSlash: false,
} satisfies ContextMenuConfig;

const ui = { contextMenu };

export default function App() {
  const editor = useRef<SuperDocRef>(null);
  const [ready, setReady] = useState(false);

  function openContextMenu() {
    const instance = editor.current?.getInstance();
    if (!instance) return;
    const result = instance.ui.contextMenu.open();
    if (!result.ok) console.warn(`Context menu did not open: ${result.reason}`);
  }

  return (
    <>
      <button type='button' disabled={!ready} onClick={openContextMenu}>
        Open context menu
      </button>
      <SuperDocEditor ref={editor} document='/sample.docx' onReady={() => setReady(true)} ui={ui} />
    </>
  );
}

```


Vanilla also needs the button and Editor mount:

```html
<button id="open-context-menu" type="button">Open context menu</button>
<div id="editor"></div>

<script type="module" src="/src/main.ts"></script>

```

`open()` returns `{ ok: false, reason }` when it cannot open. This includes an Editor that is not ready, a read-only
document, or missing selection geometry. Call `superdoc.ui.contextMenu.close()` to dismiss the menu; calling `close()`
when it is already closed is safe.

Continue with [Application-owned context menus](/editor/custom-ui/context-menus) when your application should render the
surface, or [Content controls](/editor/built-in-ui/content-controls) to configure structured fields in a DOCX.