Context Menu

Context Menu presents secondary actions at the pointer after a right click or long press.

Purpose

Context Menu presents secondary actions at the pointer after a right click or long press. Keep primary actions visible outside the menu.

Object actions

Right click file row

import { ContextMenu, ContextMenuItem, ContextMenuPopup, ContextMenuTrigger } from "@/components/ui/context-menu";

export function Example() {
  return (
    <ContextMenu>
      <ContextMenuTrigger render={<div />}>Right click target</ContextMenuTrigger>
      <ContextMenuPopup><ContextMenuItem>Duplicate</ContextMenuItem></ContextMenuPopup>
    </ContextMenu>
  );
}

Installation

With the Siteplane registry alias configured, add the component and import the installed source from your app.

CLI

pnpm dlx shadcn@4.16.1 add @siteplane/context-menu

Import

import { ContextMenu, ContextMenuCheckboxItem, ContextMenuGroup, ContextMenuGroupLabel, ContextMenuItem, ContextMenuLinkItem, ContextMenuPopup, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubPopup, ContextMenuSubTrigger, ContextMenuTrigger } from "@/components/ui/context-menu";

Need the machine-readable source metadata? View registry JSON.

Usage

Context Menu handles right-click actions for an object. Keep the trigger surface clear about what owns the menu.

import { ContextMenu, ContextMenuItem, ContextMenuPopup, ContextMenuTrigger } from "@/components/ui/context-menu";

export function Example() {
  return (
    <ContextMenu>
      <ContextMenuTrigger render={<div />}>Right click target</ContextMenuTrigger>
      <ContextMenuPopup><ContextMenuItem>Duplicate</ContextMenuItem></ContextMenuPopup>
    </ContextMenu>
  );
}

Examples

Icons, groups, selection items, link items and submenus reuse the shared menu styling on a right-click surface.

With icons and shortcuts

Right click here

<ContextMenu>
  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
  <ContextMenuPopup className="w-48">
    <ContextMenuItem>
      <PencilIcon aria-hidden="true" />
      Edit
      <ContextMenuShortcut>⌘E</ContextMenuShortcut>
    </ContextMenuItem>
    <ContextMenuItem>
      <CopyIcon aria-hidden="true" />
      Copy
      <ContextMenuShortcut>⌘C</ContextMenuShortcut>
    </ContextMenuItem>
    <ContextMenuSeparator />
    <ContextMenuItem variant="destructive">
      <TrashIcon aria-hidden="true" />
      Delete
      <ContextMenuShortcut>⌘⌫</ContextMenuShortcut>
    </ContextMenuItem>
  </ContextMenuPopup>
</ContextMenu>

Grouped

Right click here

<ContextMenu>
  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
  <ContextMenuPopup>
    <ContextMenuGroup>
      <ContextMenuGroupLabel>File</ContextMenuGroupLabel>
      <ContextMenuItem>Rename</ContextMenuItem>
      <ContextMenuItem>Duplicate</ContextMenuItem>
    </ContextMenuGroup>
    <ContextMenuSeparator />
    <ContextMenuGroup>
      <ContextMenuGroupLabel>Share</ContextMenuGroupLabel>
      <ContextMenuItem>Send copy</ContextMenuItem>
      <ContextMenuItem>Export</ContextMenuItem>
    </ContextMenuGroup>
  </ContextMenuPopup>
</ContextMenu>

Checkbox items

Right click here

<ContextMenu>
  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
  <ContextMenuPopup>
    <ContextMenuCheckboxItem defaultChecked>
      Show hidden files
    </ContextMenuCheckboxItem>
    <ContextMenuCheckboxItem>Compact view</ContextMenuCheckboxItem>
  </ContextMenuPopup>
</ContextMenu>

Radio items

Right click here

<ContextMenu>
  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
  <ContextMenuPopup>
    <ContextMenuRadioGroup defaultValue="system">
      <ContextMenuRadioItem value="light">Light</ContextMenuRadioItem>
      <ContextMenuRadioItem value="dark">Dark</ContextMenuRadioItem>
      <ContextMenuRadioItem value="system">System</ContextMenuRadioItem>
    </ContextMenuRadioGroup>
  </ContextMenuPopup>
</ContextMenu>

Switch items

variant="switch" stays a semantic checkbox item.

Right click here

<ContextMenu>
  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
  <ContextMenuPopup>
    <ContextMenuCheckboxItem defaultChecked variant="switch">
      Auto save
    </ContextMenuCheckboxItem>
    <ContextMenuCheckboxItem variant="switch">Show preview</ContextMenuCheckboxItem>
  </ContextMenuPopup>
</ContextMenu>

Link items

Router links use ContextMenuLinkItem with render instead of turning an item into a link.

Right click here

<ContextMenu>
  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
  <ContextMenuPopup>
    <ContextMenuLinkItem render={<Link href="/docs" />}>Documentation</ContextMenuLinkItem>
    <ContextMenuLinkItem render={<Link href="/docs/documentation/motion" />}>Motion</ContextMenuLinkItem>
  </ContextMenuPopup>
</ContextMenu>

Submenu

Right click here

<ContextMenu>
  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
  <ContextMenuPopup>
    <ContextMenuItem>Cut</ContextMenuItem>
    <ContextMenuItem>Copy</ContextMenuItem>
    <ContextMenuItem>Paste</ContextMenuItem>
    <ContextMenuSub>
      <ContextMenuSubTrigger>Share</ContextMenuSubTrigger>
      <ContextMenuSubPopup>
        <ContextMenuItem>Email link</ContextMenuItem>
        <ContextMenuItem>Messages</ContextMenuItem>
        <ContextMenuItem>Notes</ContextMenuItem>
      </ContextMenuSubPopup>
    </ContextMenuSub>
  </ContextMenuPopup>
</ContextMenu>

Functional actions

Right click here

Last action: none

const [status, setStatus] = useState("Last action: none");

<ContextMenu>
  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
  <ContextMenuPopup>
    <ContextMenuItem onClick={() => setStatus("Last action: Cut")}>Cut</ContextMenuItem>
    <ContextMenuItem onClick={() => setStatus("Last action: Copy")}>Copy</ContextMenuItem>
    <ContextMenuItem onClick={() => setStatus("Last action: Paste")}>Paste</ContextMenuItem>
    <ContextMenuSeparator />
    <ContextMenuItem onClick={() => setStatus("Last action: Delete")} variant="destructive">
      Delete
    </ContextMenuItem>
  </ContextMenuPopup>
</ContextMenu>
<p className="text-muted-foreground text-xs">{status}</p>

API Reference

The reference lists the source-owned exports and props that are easy to miss in visual examples. Inherited Base UI props remain available unless the wrapper narrows them.

ContextMenuPopup width accepts "auto", "trigger", "content", or "at-least-trigger"; use the prop instead of hardcoded width classes.
Popup placement is controlled by side, align, sideOffset, and alignOffset. Defaults are bottom, start, and zero side offset.
Use inset on items, group labels, and submenu triggers to align rows without leading icons.
ContextMenuCheckboxItem size accepts "sm", "default", "lg", and "xl".
All item, selection, label, separator, and submenu rows inherit the provider controlSize; repeated rows use the compact menu geometry from the global size contract rather than the 56px XL CTA height.
ContextMenuLinkItem closeOnClick defaults to true; set it to false only when navigation must leave the menu open.
Use disabled for unavailable actions.
Use ContextMenuLinkItem for navigation instead of adding link behavior to a command item.

Motion

Component motion uses the shared Siteplane motion contract. See the global motion guide for provider setup, tokens and reduced-motion behavior.

Popup and submenu scale, fade, placement, and reduced-motion behavior are native to Context Menu.
Active items and submenu triggers use a pointer cursor.
Do not add a second popup transition.

Accessibility

The trigger target needs visible context that explains what will receive the actions.
Preserve right-click, long-press, keyboard, focus, Escape, and dismissal behavior.
Keep disabled items unavailable and visibly distinct.
Checkbox and radio items must retain their selection indicators.

Implementation Guidance

Use Context Menu only for pointer-related secondary actions.
Keep primary actions visible and discoverable elsewhere.
Use width, placement, inset, size, disabled, and link props instead of local menu styling.
Preserve native item, submenu, selection, cursor, and focus behavior.

Purpose

Object actions

Installation

CLI

Import

Usage

Examples

With icons and shortcuts

Grouped

Checkbox items

Radio items

Switch items

Link items

Submenu

Functional actions

API Reference

Motion

Accessibility

Implementation Guidance

On This Page