Shadcn Context Menu for React and Tailwind

Installation

bunx --bun shadcn@latest add https://kit.dev/r/context-menu.json

pnpm dlx shadcn@latest add https://kit.dev/r/context-menu.json

npx shadcn@latest add https://kit.dev/r/context-menu.json

yarn shadcn@latest add https://kit.dev/r/context-menu.json

bun add @ark-ui/react tailwind-variants lucide-react

pnpm add @ark-ui/react tailwind-variants lucide-react

npm install @ark-ui/react tailwind-variants lucide-react

yarn add @ark-ui/react tailwind-variants lucide-react

"use client";

import {
  Menu as ArkMenu,
  useMenu as useArkMenu,
  useMenuContext as useArkMenuContext,
  useMenuItemContext as useArkMenuItemContext,
} from "@ark-ui/react/menu";
import type React from "react";
import { cn } from "@/lib/utils";
import {
  Menu,
  MenuArrow,
  MenuCheckboxItem,
  MenuContent,
  MenuGroup,
  MenuGroupLabel,
  MenuItem,
  MenuQuickItem,
  MenuRadioGroup,
  MenuRadioItem,
  MenuSeparator,
  MenuShortcut,
  MenuSub,
  MenuSubContent,
  MenuSubTrigger,
} from "@/components/ui/menu";

export const useContextMenu = useArkMenu;
export const useContextMenuContext = useArkMenuContext;
export const useContextMenuItemContext = useArkMenuItemContext;

export const ContextMenuContext: typeof ArkMenu.Context = ArkMenu.Context;
export const ContextMenuItemContext: typeof ArkMenu.ItemContext =
  ArkMenu.ItemContext;

export const ContextMenu = (props: React.ComponentProps<typeof Menu>) => {
  const { positioning = { placement: "bottom-start" }, ...rest } = props;

  return <Menu data-slot="context-menu" positioning={positioning} {...rest} />;
};

export const ContextMenuRootProvider = (
  props: React.ComponentProps<typeof ArkMenu.RootProvider>
) => {
  const { lazyMount = true, unmountOnExit = true, ...rest } = props;

  return (
    <ArkMenu.RootProvider
      data-slot="context-menu"
      lazyMount={lazyMount}
      unmountOnExit={unmountOnExit}
      {...rest}
    />
  );
};

export const ContextMenuTrigger = (
  props: React.ComponentProps<typeof ArkMenu.ContextTrigger>
) => {
  const { children, className, ...rest } = props;
  const child =
    Array.isArray(children) && children.length === 1 ? children[0] : children;

  return (
    <ArkMenu.ContextTrigger
      className={cn("cursor-default", className)}
      data-slot="context-menu-trigger"
      {...rest}
    >
      {child}
    </ArkMenu.ContextTrigger>
  );
};

export const ContextMenuContent = (
  props: React.ComponentProps<typeof MenuContent>
) => <MenuContent data-slot="context-menu-content" {...props} />;

export const ContextMenuGroup = (
  props: React.ComponentProps<typeof MenuGroup>
) => <MenuGroup data-slot="context-menu-group" {...props} />;

export const ContextMenuGroupLabel = (
  props: React.ComponentProps<typeof MenuGroupLabel>
) => <MenuGroupLabel data-slot="context-menu-group-label" {...props} />;

export const ContextMenuSeparator = (
  props: React.ComponentProps<typeof MenuSeparator>
) => <MenuSeparator data-slot="context-menu-separator" {...props} />;

export const ContextMenuItem = (
  props: React.ComponentProps<typeof MenuItem>
) => <MenuItem data-slot="context-menu-item" {...props} />;

export const ContextMenuQuickItem = (
  props: React.ComponentProps<typeof MenuQuickItem>
) => <MenuQuickItem data-slot="context-menu-quick-item" {...props} />;

export const ContextMenuCheckboxItem = (
  props: React.ComponentProps<typeof MenuCheckboxItem>
) => <MenuCheckboxItem data-slot="context-menu-checkbox-item" {...props} />;

export const ContextMenuRadioGroup = (
  props: React.ComponentProps<typeof MenuRadioGroup>
) => <MenuRadioGroup data-slot="context-menu-radio-group" {...props} />;

export const ContextMenuRadioItem = (
  props: React.ComponentProps<typeof MenuRadioItem>
) => <MenuRadioItem data-slot="context-menu-radio-item" {...props} />;

export const ContextMenuSub = (props: React.ComponentProps<typeof MenuSub>) => (
  <MenuSub data-slot="context-menu-sub" {...props} />
);

export const ContextMenuSubContent = (
  props: React.ComponentProps<typeof MenuSubContent>
) => <MenuSubContent data-slot="context-menu-sub-content" {...props} />;

export const ContextMenuSubTrigger = (
  props: React.ComponentProps<typeof MenuSubTrigger>
) => <MenuSubTrigger data-slot="context-menu-sub-trigger" {...props} />;

export const ContextMenuShortcut = (
  props: React.ComponentProps<typeof MenuShortcut>
) => <MenuShortcut data-slot="context-menu-shortcut" {...props} />;

export const ContextMenuArrow = (
  props: React.ComponentProps<typeof MenuArrow>
) => <MenuArrow data-slot="context-menu-arrow" {...props} />;

Anatomy

ContextMenu
├── ContextMenuTrigger
└── ContextMenuContent
    ├── ContextMenuGroup
    │   └── ContextMenuGroupLabel
    ├── ContextMenuItem
    ├── ContextMenuQuickItem
    ├── ContextMenuCheckboxItem
    ├── ContextMenuRadioGroup
    │   └── ContextMenuRadioItem
    ├── ContextMenuSub
    │   ├── ContextMenuSubTrigger
    │   └── ContextMenuSubContent
    ├── ContextMenuSeparator
    ├── ContextMenuShortcut
    └── ContextMenuArrow

ContextMenu is Menu with ContextMenuTrigger (right-click / long-press) instead of MenuTrigger (click). Content, items, groups, submenus, checkboxes, and radios are the same Menu parts. useContextMenu is the machine hook for ContextMenuRootProvider and returns { api, service }. useContextMenuContext / ContextMenuContext is in-tree (the api).

ContextMenuContent portals the list and includes the positioner. The trigger sets anchorPoint from the pointer.

Usage

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

<ContextMenu>
  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuGroup>
      <ContextMenuItem value="action-1">Action 1</ContextMenuItem>
      <ContextMenuItem value="action-2">Action 2</ContextMenuItem>
      <ContextMenuItem value="action-3">Action 3</ContextMenuItem>
    </ContextMenuGroup>
  </ContextMenuContent>
</ContextMenu>

shadcn.io Menu defaults lazyMount and unmountOnExit to true (Ark: false). Context Menu defaults positioning.placement to "bottom-start" (Menu: "bottom-end"). Give every item a stable value.

Controlled

Control open state with open and onOpenChange. { open: boolean }.

Root Provider

Use useContextMenu with ContextMenuRootProvider when you need the API outside the tree. Pass machine options (positioning, closeOnSelect, onSelect, …) to useContextMenu(), not to the provider. The hook returns { api, service } — call menu.api.setOpen(true) and pass the whole return value to the provider.

Examples

Nested menu

Use ContextMenuSub, ContextMenuSubTrigger, and ContextMenuSubContent for nested submenus.

Icons

Combine icons with labels for quick scanning. Decorative icons should be aria-hidden="true".

Shortcuts

Use ContextMenuShortcut to show keyboard hints next to items.

Checkboxes

Use ContextMenuCheckboxItem for toggles. Control with checked and onCheckedChange.

Radio group

Use ContextMenuRadioGroup and ContextMenuRadioItem for a single choice. onValueChange receives { value: string }.

With link

Use asChild on ContextMenuItem with an <a> or Next.js Link.

With group label

Use ContextMenuGroup with heading or ContextMenuGroupLabel.

With separator

Use ContextMenuSeparator between related groups.

Quick items

Use ContextMenuQuickItem for icon-above-text actions in a horizontal row.

Scrollable

Add max-h-* and overflow (already overflow-y-auto on content) to cap height.

Open a dialog

Open a Dialog from onSelect on an item.

Destructive

Use variant="destructive" on ContextMenuItem for irreversible actions.

Context

Read open and highlighted state with ContextMenuContext or useContextMenuContext.

Guides

Context Menu vs Menu

Use Menu for a button-triggered dropdown. Use Command when the list is searchable.

Pointer position

ContextMenuTrigger sets anchorPoint from the pointer. positioning.placement is relative to that point. Override with positioning on ContextMenu (or on useContextMenu()).

<ContextMenu positioning={{ placement: "right-start", gutter: 8 }}>

Custom trigger surface

ContextMenuTrigger renders a button by default. Merge onto a card, image, or other host with asChild and a single child.

<ContextMenuTrigger asChild>
  <div className="rounded-xl border p-6">Right click the card</div>
</ContextMenuTrigger>

The host should be focusable if keyboard users need the same actions (Shift+F10 / context-menu key). Offer a visible Menu on small viewports where long-press is not obvious.

Item values

Every ContextMenuItem, checkbox, radio, and submenu item needs a unique value. Typeahead and highlight tracking use it.

API Reference

shadcn.io Context Menu wraps Menu (Ark Menu machine). Defaults below are shadcn.io Context Menu values. lazyMount / unmountOnExit are true (Ark: false). positioning.placement is "bottom-start" (Menu: "bottom-end"). data-scope stays menu; shadcn.io sets data-slot="context-menu" on the root.

asChild merges props onto a single child element.

ContextMenu

Root. Same as Menu besides the placement default. Renders no extra chrome; content is created by ContextMenuContent.

ContextMenuTrigger

Opens the menu on right-click or long-press. Renders a button.

ContextMenuContent

Portaled list surface. Includes the positioner. Renders a div.

ContextMenuItem

A single action. Renders a div. value is required.

ContextMenuCheckboxItem

Toggle item. Indicator is built in.

ContextMenuRadioGroup

Mutually exclusive options. Pass heading to render ContextMenuGroupLabel.

ContextMenuRadioItem

A single option in a radio group. Indicator is built in.

ContextMenuGroup

Groups related items. Pass heading to render ContextMenuGroupLabel.

ContextMenuGroupLabel

Label for a group. Usually created by heading on ContextMenuGroup. Renders a div.

ContextMenuSeparator

Visual divider. Renders a hr.

ContextMenuQuickItem

Item with icon-above-text layout. Same props as ContextMenuItem. Use in a horizontal flex row.

ContextMenuSub / ContextMenuSubTrigger / ContextMenuSubContent

Nested menu. Wrap ContextMenuSubTrigger and ContextMenuSubContent in ContextMenuSub. ContextMenuSub is another Menu root (data-slot="context-menu-sub"). ContextMenuSubContent is portaled.

ContextMenuSubTrigger renders a trigger item with a chevron. ContextMenuSub accepts the same root props as ContextMenu.

ContextMenuShortcut

Keyboard hint aligned to the end of an item. Renders a span.

ContextMenuArrow

Optional arrow toward the anchor. Less common for pointer menus.

ContextMenuRootProvider

Root alternative that takes { api, service } from useContextMenu(). Presence (lazyMount, unmountOnExit) can still be set on the provider.

Pass positioning, closeOnSelect, and other machine options to useContextMenu(), not to ContextMenuRootProvider. To match ContextMenu, pass positioning: { placement: "bottom-start" }.

useContextMenu

Creates the menu API for ContextMenuRootProvider. Returns { api, service } — not the api alone.

const menu = useContextMenu({
  positioning: { placement: "bottom-start" },
});

menu.api.setOpen(true);

ContextMenuContext / useContextMenuContext

Render-prop or hook access to menu state (the api). Use inside ContextMenu or ContextMenuRootProvider.

ContextMenuContext children: (context) => ReactNode.

ContextMenuItemContext / useContextMenuItemContext

Render-prop or hook access to one item. Use inside an item.

ContextMenuItemContext children: (context) => ReactNode.

Accessibility

Complies with the Menu WAI-ARIA design pattern. The trigger should be reachable from the keyboard when the same actions are required without a pointer. Label icon-only items. Keep destructive actions on variant="destructive" and confirm them in a Dialog when needed.

Keyboard support