ContextMenu
Open item-specific actions at a context interaction point.
Anatomy#
Content is portaled; grouped items use the same item subtree as ungrouped items.
Usage#
Use ContextMenu for actions tied to a specific surface or item at the pointer location. Use DropdownMenu when the same actions open from a visible trigger. Use Popover when the content is not a list of commands. Use Dialog when the user must complete or confirm a modal task. Keep essential actions reachable through another visible path.
Triggering the menu#
Wrap the target with ContextMenu.Trigger. The menu opens at the pointer on right-click, or at the
center of the trigger when opened from the keyboard. A touch or pen long press (700 ms) also opens it.
The trigger renders a div; pass as to render another element. With disabled on the root, the
native browser menu shows instead.
Item models#
The items array describes the whole menu. An item has type 'item' (the default), 'checkbox',
'radio-group', 'group', or 'separator'; an item with children opens a submenu. Items accept
icon, description, kbds, disabled, and variant: 'danger'. kbds only displays keycaps and
does not register a shortcut. An entry that is an array of items forms its own group, and the menu
draws a separator between groups.
Checkbox and radio state is controlled with checked / onCheckedChange and with value /
onValueChange on the radio-group (not on each radio). Omit them to let the item manage its own
state, starting from defaultChecked or defaultValue. Selecting a checkbox or radio keeps the menu
open; selecting a regular item runs onSelect and closes it.
A parent item with children can take open and onOpenChange to control its submenu.
onOpenChange reports every open or close request from pointer, keyboard, or click interaction. With
a controlled open, the submenu stays at the prop value until you update it.
ContextMenu.Content also takes headerRender and footerRender to add a header (such as the
target’s metadata) or a footer around the item groups, in the root menu and in every submenu. Both
receive { sub }. itemRender replaces the inner content of every item row; the row keeps its role,
keyboard handling, and selection.
Dismissal and scrolling#
Escape and outside presses close the menu. Set closeOnEscape or closeOnOutsideClick to false to
block them, and use onClosePrevented to react to the blocked attempt. While the menu is open, body
scroll is locked and an overlay renders behind the content; set preventScroll to false to keep the
page scrollable. Set modal to hide outside content from assistive technology while the menu is open.
Keyboard interaction#
| Key | Description |
|---|---|
| Shift + F10 / ContextMenu | Toggles the menu from the focused trigger. |
| ↓ / ↑ | Moves focus to the next or previous item. |
| ↖ / ↘ | Moves focus to the first or last item. |
| Printable characters | Moves focus to the next item whose text starts with the typed characters. |
| → | Opens the submenu of the focused item. |
| ← | Closes the current submenu and returns to its parent item. |
| ↵ / Space | Activates the focused item, or opens its submenu. |
| Esc | Closes the current menu layer and restores focus. |
| ⇥ | Closes the menu. |
Examples#
Open page actions on a selected surface#
Right-click or long-press the dashed region. Forward stays disabled in this example.
Copy, rename, or delete a file#
Describe grouped actions in the item model, including a danger-variant delete.
Manage a project file#
Move a file between folders, add it to favorites, or move it to the trash and undo. These actions update local example state; permission-dependent actions remain disabled.
Pin an item and set priority#
Checkbox and radio values live in application state. The status line reflects the current pin and priority.
Sort from a nested menu#
Nested children open a sort submenu. Refresh stays on the root menu.
Copy a note on long press#
Touch and hold for about 700 ms, or right-click, to copy or delete the note.
API Reference#
Attributes#
data-closeddata-disableddata-expandeddata-aligndata-sidedata-dangerdata-highlighteddata-selectedProps#
ContextMenu#
Trigger#
Renders a <div> element by default.
Content#
Props for the ContextMenu content component. Renders a <div> element by default.