Context menu

• Type: Component (actions)
• Access: Free, open source
• Page: https://ui.xzero.co.uk/components/context-menu
• Markdown: https://ui.xzero.co.uk/components/context-menu/markdown
• Registry item: https://mcp.xzero.co.uk/r/context-menu.json
• Source file: registry/components/context-menu/context-menu.tsx
• Dependencies: motion, lucide-react
• Keywords: menu, action, react context menu, right click menu, custom context menu, file actions menu, shift f10 menu, animated context menu

When to use

• Secondary actions on a file, card, or row where a visible menu button would add clutter.
• Desktop-style right-click menus that also open from the keyboard with Shift+F10 or the ContextMenu key.
• Short flat lists of item actions with one destructive option.

When not to use

• Use dropdown-menu when the actions deserve a visible trigger.
• Use swipe-actions for touch-first lists like an inbox.
• Avoid it on targets that need their own click action, since a plain click on the target also opens the menu.

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui/context-menu

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { ContextMenu } from "@/components/xzero/context-menu/context-menu";
import { Copy, Trash2 } from "lucide-react";

export function FileTile({ file }: { file: File }) {
  return (
    <ContextMenu
      label={`Actions for ${file.name}`}
      items={[
        { id: "copy", label: "Copy link", icon: <Copy size={15} />, onSelect: () => copyLink(file) },
        { id: "delete", label: "Delete file", icon: <Trash2 size={15} />, destructive: true, onSelect: () => remove(file) },
      ]}
    >
      <FilePreview file={file} />
    </ContextMenu>
  );
}

API reference

ContextMenu

Wraps content and opens a menu at the pointer on right-click, or under the target on click and keyboard.

Prop	Type	Default	Description
children (required)	ReactNode	–	The target area.
items (required)	ContextMenuItem[]	–	Items: { id, label, icon?, onSelect?, disabled?, destructive?, checked? }.
label	string	"Context menu"	Accessible name for both the target and the menu.

Keyboard interactions

Keys	Action
ContextMenu / Shift+F10	Opens the menu under the focused target.
ArrowDown / ArrowUp	Moves between enabled items, wrapping at the ends.
Home / End	Jumps to the first or last enabled item.
Enter / Space	Selects the focused item and closes the menu.
Escape	Closes the menu and returns focus to the target.

Accessibility

• The target is focusable with aria-haspopup="menu" and aria-expanded; the menu has role="menu" and items role="menuitem".
• Opening focuses the first enabled item; closing returns focus to the target.
• Items without an icon show a check when checked, but checked state is not exposed to assistive tech, so say it in the label if it matters.

Motion

• The menu grows from the pointer on a snappy spring, even when clamped away from a viewport edge; reopening fades the old one out in place.
• A shared highlight glides between rows for the pointer and jumps for the keyboard.
• Reduced motion drops the scale and glide and uses a short opacity fade.

Responsive behavior

• The menu is clamped 8px inside the viewport and capped at the viewport width minus 16px, with a max height of 300px and scrolling beyond that.
• On touch, a tap on the target opens the menu under it, so it works without a right mouse button.
• The menu closes on any scroll or resize instead of repositioning.

Performance

• The menu mounts only while open and is positioned once from the pointer, with no scroll tracking loop.
• Items are plain buttons with one shared highlight element; there is no virtualization, so keep the list short.

Notes for AI

• Use for secondary actions on a content object (file, card, row) where a visible menu button would add clutter. Use dropdown-menu when the commands deserve a visible trigger.
• A plain click on the target also opens the menu, so do not wrap targets that need their own click action.
• The menu closes on scroll, resize, and outside press; keep items to a short flat list.

Related

• Dropdown menu: A focused list of actions anchored to a trigger.
• Swipe actions: Reveal row actions with a swipe, or from the same actions in a menu.
• Popover: A small anchored surface for contextual information.
• Command palette: A complete keyboard driven action surface with search, grouped results, and shortcuts.

Also in menus

• User menu: Your account, settings, theme, and sign out behind the avatar. Opens as a bottom sheet on phones.

Guidance for AI tools

Context menu: Secondary actions kept close to the selected object. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt