> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# ContextMenu

Navigation`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Displays contextual actions from a right click or long press interaction.

## When to use

Use ContextMenu for secondary actions attached to an object or region.

**Recommended**

- Keep items short and action-oriented.
- Provide another reachable path for critical actions.

**Avoid**

- Do not put primary workflows only inside a context menu.

## Examples


### Basic usage
```tsx preview
import { ContextMenu } from '@rockshin/tao-ui';

function ContextMenuExample() {
  return (
    <ContextMenu
      menu={{
        items: [
          { key: 'cut', label: 'Cut', extra: '⌘X' },
          { key: 'copy', label: 'Copy', extra: '⌘C' },
          { key: 'paste', label: 'Paste', extra: '⌘V' },
          { type: 'divider' },
          { key: 'delete', label: 'Delete', danger: true },
        ],
      }}
    >
      <div
        style={{
          padding: 32,
          border: '1px dashed var(--tao-color-border)',
          borderRadius: 8,
        }}
      >
        Right-click this area
      </div>
    </ContextMenu>
  );
}

export default ContextMenuExample;
```

### Groups, disabled items, and submenus
```tsx preview
import { ContextMenu } from '@rockshin/tao-ui';

function ContextMenuGroups() {
  return (
    <ContextMenu
      menu={{
        items: [
          {
            type: 'group',
            label: 'View',
            children: [
              { key: 'zoom-in', label: 'Zoom in' },
              { key: 'zoom-out', label: 'Zoom out' },
            ],
          },
          { type: 'divider' },
          {
            key: 'share',
            label: 'Share',
            children: [
              { key: 'copy-link', label: 'Copy link' },
              { key: 'email', label: 'Email' },
            ],
          },
          { key: 'locked', label: 'Locked action', disabled: true },
        ],
      }}
    >
      <div
        style={{
          padding: 32,
          border: '1px dashed var(--tao-color-border)',
          borderRadius: 8,
        }}
      >
        Right-click for grouped actions
      </div>
    </ContextMenu>
  );
}

export default ContextMenuGroups;
```

### Selectable menu items
```tsx preview
import { ContextMenu } from '@rockshin/tao-ui';
import { useState } from 'react';

function SelectableContextMenu() {
  const [selected, setSelected] = useState(['comfortable']);

  return (
    <ContextMenu
      menu={{
        selectable: true,
        selectedKeys: selected,
        onSelect: ({ selectedKeys }) => setSelected(selectedKeys),
        items: [
          { key: 'compact', label: 'Compact' },
          { key: 'comfortable', label: 'Comfortable' },
          { key: 'spacious', label: 'Spacious' },
        ],
      }}
    >
      <div
        style={{
          padding: 32,
          border: '1px dashed var(--tao-color-border)',
          borderRadius: 8,
        }}
      >
        Current density: {selected[0]}
      </div>
    </ContextMenu>
  );
}

export default SelectableContextMenu;
```

### Groups and submenus
Organize actions with groups and nested `children`; mark destructive actions with `danger`. Right-click the area.
```tsx preview
import { ContextMenu } from '@rockshin/tao-ui';

function Area({ children = 'Right-click here' }: { children?: string }) {
  return (
    <div
      style={{
        display: 'grid',
        placeItems: 'center',
        width: 320,
        height: 160,
        border: '1px dashed var(--tao-color-border)',
        borderRadius: 8,
        color: 'var(--tao-color-text-tertiary)',
        fontSize: 13,
        userSelect: 'none',
      }}
    >
      {children}
    </div>
  );
}

export default function ContextMenuGroupsAndSubmenu() {
  return (
    <ContextMenu
      menu={{
        items: [
          {
            type: 'group',
            label: 'View',
            children: [
              { key: 'zoom-in', label: 'Zoom in' },
              { key: 'zoom-out', label: 'Zoom out' },
            ],
          },
          { type: 'divider' },
          {
            key: 'share',
            label: 'Share',
            children: [
              { key: 'mail', label: 'Email' },
              { key: 'link', label: 'Copy link' },
            ],
          },
          { key: 'rename', label: 'Rename' },
          { key: 'delete', label: 'Delete', danger: true },
        ],
      }}
    >
      <Area />
    </ContextMenu>
  );
}
```

### Selectable menu items
Keep selection in `selectedKeys` and `onSelect`, for example for view preferences.
```tsx preview
import { ContextMenu } from '@rockshin/tao-ui';

import { useState } from 'react';

function Area({ children = 'Right-click here' }: { children?: string }) {
  return (
    <div
      style={{
        display: 'grid',
        placeItems: 'center',
        width: 320,
        height: 160,
        border: '1px dashed var(--tao-color-border)',
        borderRadius: 8,
        color: 'var(--tao-color-text-tertiary)',
        fontSize: 13,
        userSelect: 'none',
      }}
    >
      {children}
    </div>
  );
}

export default function ContextMenuSelectable() {
  const [checked, setChecked] = useState<string[]>(['grid']);
  return (
    <ContextMenu
      menu={{
        selectable: true,
        multiple: true,
        selectedKeys: checked,
        onSelect: ({ selectedKeys }) => setChecked(selectedKeys),
        items: [
          { key: 'grid', label: 'Show grid' },
          { key: 'ruler', label: 'Show ruler' },
          { key: 'guides', label: 'Show guides' },
        ],
      }}
    >
      <Area>{`Right-click — ${checked.length} shown`}</Area>
    </ContextMenu>
  );
}
```

### Disabled context menu
`disabled` turns off the custom menu. Keep essential actions available outside a context menu.
```tsx preview
import { ContextMenu, type MenuItem } from '@rockshin/tao-ui';

function Area({ children = 'Right-click here' }: { children?: string }) {
  return (
    <div
      style={{
        display: 'grid',
        placeItems: 'center',
        width: 320,
        height: 160,
        border: '1px dashed var(--tao-color-border)',
        borderRadius: 8,
        color: 'var(--tao-color-text-tertiary)',
        fontSize: 13,
        userSelect: 'none',
      }}
    >
      {children}
    </div>
  );
}

export default function ContextMenuDisabled() {
  return (
    <ContextMenu
      menu={{
        items: [
          { key: 'undo', label: 'Undo', extra: '⌘Z' },
          { key: 'redo', label: 'Redo', disabled: true, extra: '⇧⌘Z' },
          { type: 'divider' },
          { key: 'select-all', label: 'Select all', extra: '⌘A' },
        ] as MenuItem[],
      }}
    >
      <Area />
    </ContextMenu>
  );
}
```

## API


### [#](#contextmenu)ContextMenu



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| children | Element whose right-click (long-press on touch) opens the menu. | `ReactNode` **(Required)** | `-` |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| className | Merged onto the floating content. | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |

