# Context Menu

Actions that open on right-click, styled like the dropdown menu.

- Category: Navigation & Layout
- Page: https://wunderui.com/components/context-menu
- Tier: Core and Pro

## Install

Context Menu ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { ContextMenu, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuSeparator, ContextMenuTrigger } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuTrigger,
} from "@/components/ui/context-menu"

export function ProjectCard() {
  return (
    <ContextMenu>
      <ContextMenuTrigger
        tabIndex={0}
        className="grid h-40 place-items-center rounded-xl border border-dashed border-border-control text-sm text-text-secondary outline-none focus-ring"
      >
        Right-click here
      </ContextMenuTrigger>
      <ContextMenuContent className="w-48">
        <ContextMenuItem>Rename</ContextMenuItem>
        <ContextMenuItem>Duplicate</ContextMenuItem>
        <ContextMenuSeparator />
        <ContextMenuItem variant="destructive">Delete project</ContextMenuItem>
      </ContextMenuContent>
    </ContextMenu>
  )
}
```

Expected result: You see a dashed area that says Right-click here. A right click or Shift+F10 opens a menu with Rename, Duplicate and a red Delete project after a rule; Escape closes it.

## When to use

### Use Context Menu for

- Shortcuts for an object people already work with: a file, a table row, a message, an item on a canvas
- Actions that are also reachable somewhere visible, such as a toolbar or a button on the row
- Dense work surfaces where a menu button on every row would crowd the layout

### Use something else

- [Dropdown Menu](https://wunderui.com/components/dropdown-menu) for actions behind a visible button, and menus with checkbox or radio choices and submenus
- [Popover](https://wunderui.com/components/popover) for content with controls of its own, not a list of actions
- [Command](https://wunderui.com/components/command) for a searchable list of every action in the app

## Keyboard

The trigger is a plain div, so it joins the tab order only with a tabIndex of 0. The Menu key or Shift+F10 then opens the menu, and the arrow keys move between items.

| Key | Action |
|---|---|
| `Menu` or `Shift+F10` | On a focused trigger: opens the menu, in Chrome at the centre of the trigger. The browser sends the same event as a right click. |
| `ArrowDown` or `ArrowUp` | Moves focus to the next or previous item. The first press focuses the first item. Disabled items are reached too, and focus wraps at the ends. |
| `Home` or `End` | Moves focus to the first or the last item. |
| `A–Z` | Type-ahead: typing the start of a label moves focus to the next item that begins with it. |
| `Enter` or `Space` | Runs the focused item and closes the menu. Focus goes back to the trigger. |
| `Escape` | Closes the menu and returns focus to the trigger. |

While the menu is open the page behind it is inert and does not scroll. Tab does nothing in an open menu, so close it with Escape first.

## Behavior

What the menu does with the gesture, focus, position and motion.

- **Opening:** A right click opens the menu with its corner at the pointer, and a 500 ms press does the same on touch. A disabled menu does not open, so the browser menu shows.
- **Items and activation:** A click or Enter runs the item and closes the menu. A disabled item is dimmed and cannot run, but it stays focusable and is announced as unavailable.
- **Focus:** Focus moves into the menu when it opens and back to the trigger when it closes. A trigger that cannot take focus loses it to the page, another reason to make it focusable.
- **Modal:** The menu is modal, like a native one. The page behind it is inert and does not scroll, and a click outside closes it.
- **Position and size:** The menu opens at the pointer and flips or shifts when there is no room. It is at least 10 rem wide, as tall as its items, and scrolls when the room runs out.
- **Mirror the actions:** A right click is hard to discover and missing on some devices. Put the same actions where everyone can reach them: the menu is a shortcut, never the only way.
- **Previews in these docs:** The real menu is portalled to the end of the document. The previews here draw it inside the card and start closed, because a context menu opens on the reader's own gesture.
- **Opening and closing:** The menu fades in and scales up from 97%, and closes a step faster with a fade and a scale to 99%.
- **Reduced motion:** With reduced motion the scale is removed and only the fade stays, so the menu still arrives and leaves visibly without moving.

## Anatomy

- `ContextMenu`: Holds the open state and links the trigger to the menu. Control it or leave it uncontrolled, and disable it to switch the menu off; it renders nothing itself.
- `ContextMenuTrigger`: The region that opens the menu on a right click, the Menu key, Shift+F10 or a 500 ms long press on touch. It is not focusable by itself, so add a tabIndex of 0 for the keyboard.
- `ContextMenuContent`: The menu itself. It opens at the pointer, flips and shifts to stay on screen, is at least 10 rem wide and scrolls when it is taller than the room left.
- `ContextMenuGroup`: Groups related items. A label inside it becomes the accessible name of the group.
- `ContextMenuLabel`: A small heading for a group of items. It is not an item, so arrow keys skip it.
- `ContextMenuItem`: An action that runs on click and closes the menu. Add an icon before the label and use the destructive variant for red; a disabled item stays focusable so people can find it.
- `ContextMenuSeparator`: A one pixel rule between two sets of items. Put the destructive item after one.

## Best practices

### Do

- Mirror every action somewhere visible: a toolbar, a button on the row or a shortcut. The menu opens only on a context gesture, so touch and keyboard users may never find it.
- Make the trigger focusable and give it a role and a name, such as group with an aria-label. Then the Menu key and Shift+F10 work.
- Put the most used action first and the destructive one last, after a separator, named after action and object: Delete project, not Delete.
- Keep labels short verbs. The trigger already names the object, so Rename is enough.

### Don't

- Don't use a context menu to navigate or hold a form. It is a menu of commands, and links to pages belong on the page.
- Don't take over the browser menu where people expect it, such as on a text field or an image to copy. Disable the menu there and the browser one shows.
- Don't expect checkbox, radio or submenu entries. This menu has items, labels, groups and separators; use Dropdown Menu for the rest.

## API reference

### ContextMenu

| Prop | Type | Default | Description |
|---|---|---|---|
| actionsRef | React.RefObject<MenuRoot.Actions \| null> |  | A ref to imperative actions. - `unmount`: Manually unmounts the menu. Call this after any externally controlled closing animation finishes. - `close`: When specified, the menu can be closed imperatively. |
| children | React.ReactNode |  | The trigger and the content. |
| closeParentOnEsc | Menu.Root.Props['closeParentOnEsc'] |  |  |
| defaultOpen | boolean | false | Whether the menu is initially open. To render a controlled menu, use the `open` prop instead. |
| disabled | boolean | false | Switches the menu off. The trigger no longer prevents the browser's own context menu, so that one shows instead. |
| highlightItemOnHover | boolean | true | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. |
| loopFocus | boolean | true | Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys. |
| onOpenChange | ((open: boolean, eventDetails: ContextMenuRoot.ChangeEventDetails) => void) |  | Event handler called when the menu is opened or closed. |
| onOpenChangeComplete | ((open: boolean) => void) |  | Event handler called after any animations complete when the menu is opened or closed. |
| open | boolean |  | Whether the menu is currently open. |
| orientation | "horizontal" \| "vertical" | 'vertical' | The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys. |

### ContextMenuContent

| Prop | Type | Default | Description |
|---|---|---|---|
| children | React.ReactNode |  | The items, labels, groups and separators of the menu. |
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| finalFocus | boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| HTMLElement \| null \| void) |  | Determines the element to focus when the menu is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`:… |
| id | string |  | The `id` of the menu element. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### ContextMenuGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| children | React.ReactNode |  | The content of the component. |
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### ContextMenuItem

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| closeOnClick | boolean | true | Whether to close the menu when the item is clicked. |
| disabled | boolean | false | Whether the component should ignore user interaction. |
| id | string |  | The `id` of the item element. |
| label | string |  | Overrides the text label to use when the item is matched during keyboard text navigation. |
| nativeButton | boolean | false | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| onClick | BaseUIComponentProps<'div', MenuItemState>['onClick'] |  | The click handler for the menu item. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |
| variant | "default" \| "destructive" | "default" | `default` or `destructive`. The destructive item is red and gets a red tint on focus. |

Also accepts React.HTMLAttributes attributes.

### ContextMenuLabel

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### ContextMenuSeparator

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| orientation | "horizontal" \| "vertical" | 'horizontal' | The orientation of the separator. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### ContextMenuTrigger

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

## Examples

### Trigger: an area, a row or a tile

### Items: plain, with an icon, or destructive

### Structure: a separator or labelled groups

### States: enabled, an item disabled, the menu disabled

## In context

### Project files with the same actions in a toolbar

Right-click a file, or focus it and press Shift+F10, for Star, Duplicate and Delete. The toolbar offers the same three actions for the selected file, for people who never right-click.

### Messages with a menu and hover buttons

The menu on a message holds Reply, Copy text and Pin. Reply and Pin are also buttons on the message, visible on hover and focus, so nobody needs a right click.

## For AI agents

`get_component("context-menu")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
