Skip to content
WunderUI

Context Menu

Pro

Actions for the object under the pointer: a menu that opens on a right click, a long press, or the Menu key on a focused area.

Playground

Installation

Context Menu comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

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

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 for

  • Dropdown Menu for actions behind a visible button, and menus with checkbox or radio choices and submenus
  • Popover for content with controls of its own, not a list of actions
  • Command for a searchable list of every action in the app

Trigger

The trigger is any region that holds the object: an area, a list row or a grid tile. Make it focusable so the keyboard can open the menu too.

Items

An item is a label with an optional icon. Delete and remove use the destructive style and come last, after a separator.

Structure

A separator splits a menu in two. Labelled groups name the sections of a longer menu, also for screen readers.

States

A disabled item stays in the menu, dimmed. A disabled menu does not open, so the browser's own context menu shows instead.

Keyboard interactions

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.

MenuorShiftF10
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.
ArrowDownorArrowUp
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.
HomeorEnd
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.
EnterorSpace
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 and motion

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

The figure shows the open menu next to its trigger. A group has no look of its own, it only names a set of items for screen readers.

Right-click here
  • data-slot="context-menu"

    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.

  • data-slot="context-menu-trigger"

    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.

  • data-slot="context-menu-content"

    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.

  • data-slot="context-menu-group"Optional

    Groups related items. A label inside it becomes the accessible name of the group.

  • data-slot="context-menu-label"Optional

    A small heading for a group of items. It is not an item, so arrow keys skip it.

  • data-slot="context-menu-item"Optional

    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.

  • data-slot="context-menu-separator"Optional

    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.

  • Do

    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.

  • Do

    Put the most used action first and the destructive one last, after a separator, named after action and object: Delete project, not Delete.

  • Do

    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

    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

    Don't expect checkbox, radio or submenu entries. This menu has items, labels, groups and separators; use Dropdown Menu for the rest.

API reference

Context Menu wraps the Base UI context menu and passes its props on. Every part also takes a class name, a style and a render prop, and the item adds a variant.

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.

PropTypeDefaultDescription
openboolean—Whether the menu is currently open.
defaultOpenbooleanfalseWhether the menu is initially open. To render a controlled menu, use the prop instead.
onOpenChange(open, eventDetails) => void—Event handler called when the menu is opened or closed.
disabledbooleanfalseSwitches the menu off. The trigger no longer prevents the browser's own context menu, so that one shows instead.
loopFocusbooleantrueWhether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.
actionsRefRefObject<MenuRoot.Actions | null>—A ref to imperative actions. - : Manually unmounts the menu. Call this after any externally controlled closing animation finishes. - : When specified, the menu can be closed imperatively.
childrenReactNode—The trigger and the content.
closeParentOnEscMenu.Root.Props["closeParentOnEsc"]—
highlightItemOnHoverbooleantrueWhether moving the pointer over items should highlight them. Disabling this prop allows CSS to be differentiated from the () state.
onOpenChangeComplete(open) => void—Event handler called after any animations complete when the menu is opened or closed.
orientation"horizontal" | "vertical""vertical"The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys.

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.

PropTypeDefaultDescription
renderReactElement | (props, state) => ReactElement—Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a or a function that returns the element to render.

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.

PropTypeDefaultDescription
finalFocusboolean | RefObject<HTMLElement | null> | (closeType) => unknown—Determines the element to focus when the menu is closed. - : Do not move focus. - : Move focus based on the default behavior (trigger or previously focused element). - : Move focus to the ref element. - :…
idstring—The of the menu element.
childrenReactNode—The items, labels, groups and separators of the menu.

Groups related items. A label inside it becomes the accessible name of the group.

PropTypeDefaultDescription
childrenReactNode—The content of the component.

A small heading for a group of items. It is not an item, so arrow keys skip it.

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.

PropTypeDefaultDescription
variant"default" | "destructive""default" or . The destructive item is red and gets a red tint on focus.
onClickBaseUIComponentProps<"div", MenuItemState>["onClick"]—The click handler for the menu item.
disabledbooleanfalseWhether the component should ignore user interaction.
closeOnClickbooleantrueWhether to close the menu when the item is clicked.
labelstring—Overrides the text label to use when the item is matched during keyboard text navigation.
idstring—The of the item element.
nativeButtonbooleanfalseWhether the component renders a native element when replacing it via the prop. Set to if the rendered element is a native button.

A one pixel rule between two sets of items. Put the destructive item after one.

PropTypeDefaultDescription
orientation"horizontal" | "vertical""horizontal"The orientation of the separator.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("context-menu")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.