Context Menu

Installation

The component is exported from @by/experience-system. Add the package with your package manager:

pnpm add @by/experience-system

In this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.

Composition

Use the following composition to build a ContextMenu:

ContextMenu
├── ContextMenuTrigger
└── ContextMenuContent
    ├── ContextMenuLabel (optional)
    ├── ContextMenuItem / CheckboxItem / RadioGroup / …
    ├── ContextMenuSeparator (optional)
    └── ContextMenuSub (optional)
        ├── ContextMenuSubTrigger
        └── ContextMenuSubContent

ContextMenuTrigger wraps the surface that opens the menu on pointer secondary click (right-click) or the platform equivalent. Put commands and groups inside ContextMenuContent. Use ContextMenuSub for nested menus. Behavior follows Radix UI Context Menu.

Usage

import {
  ContextMenu,
  ContextMenuTrigger,
  ContextMenuContent,
  ContextMenuItem,
} from '@by/experience-system';

ContextMenu and its parts are client components ('use client'). Use them inside a Client Component or a dynamic import when using the Next.js App Router.

<ContextMenu>
  <ContextMenuTrigger className="rounded-md border border-dashed px-4 py-8">Right click</ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuItem>Action</ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>

When to use

• When you want to offer quick access to relevant actions based on the user's current selection or focus.
• When space is limited and secondary actions don't need to be always visible.

When not to use

• When the actions are critical or primary and need to be discoverable without extra clicks.
• When the number of contextual options becomes too large, leading to clutter or overwhelm.

Examples

The live preview at the top of this page uses context-menu-usage (minimal trigger + one item).

Complex content

Items with leading icons, inset alignment for icon-less rows, shortcuts, a nested submenu (including an error-styled row via color="error"), checkbox items, and a radio group with an inset label.

API Reference

Subsection titles name @by/experience-system exports and the Radix part they wrap. Pieces map to Radix UI Context Menu primitives. Styling, density-aware spacing, and icons are provided by @by/experience-system and @by/icons. Adheres to the Menu WAI-ARIA design pattern and uses roving tabindex to move focus among items.

ContextMenu

Root. ContextMenu contains all the parts of a context menu. Exported as ContextMenu; forwards ContextMenu.Root props from radix-ui.

ContextMenuTrigger

ContextMenuTrigger — the area that opens the context menu. Wrap it around the target you want the menu to open from when right-clicking (or using the relevant keyboard shortcuts).

ContextMenuPortal

ContextMenuPortal — when used, portals the content part into the document. In this experience system, container defaults to the element from useContainerElement() (ThemeProvider) instead of document.body.

ContextMenuContent

ContextMenuContent — the component that pops out in an open context menu. This export wraps Portal with the Experience System container so you typically render ContextMenuContent directly (without a separate ContextMenuPortal for the main menu).

Arrow (optional)

An optional arrow element to render alongside a submenu. This can be used to help visually link the trigger item with ContextMenu.Content. Must be rendered inside ContextMenu.Content.

@by/experience-system does not export ContextMenuArrow; ContextMenuSubTrigger includes a trailing chevron instead. For Radix’s optional arrow API, see the upstream docs.

ContextMenuItem

ContextMenuItem — the component that contains the context menu items.

ContextMenuGroup

ContextMenuGroup — used to group multiple items.

ContextMenuLabel

ContextMenuLabel — used to render a label. It will not be focusable using arrow keys.

ContextMenuCheckboxItem

ContextMenuCheckboxItem — an item that can be controlled and rendered like a checkbox. Check rendering uses ContextMenuPrimitive.ItemIndicator internally with a Check icon.

ContextMenuRadioGroup

ContextMenuRadioGroup — used to group multiple ContextMenuRadioItem components.

ContextMenuRadioItem

ContextMenuRadioItem — An item that can be controlled and rendered like a radio. The indicator is built in (ShapeBulletCircleFill).

ItemIndicator

Renders when the parent CheckboxItem or RadioItem is checked. In @by/experience-system, indicators are internal to ContextMenuCheckboxItem and ContextMenuRadioItem (not a separate export).

ContextMenuSeparator

ContextMenuSeparator — used to visually separate items in the context menu.

ContextMenuShortcut

ContextMenuShortcut — Design-system helper: a span for keyboard hints, aligned to the trailing edge when placed inside an item. Not a Radix primitive part.

ContextMenuSub

ContextMenuSub — contains all the parts of a submenu.

ContextMenuSubTrigger

ContextMenuSubTrigger — an item that opens a submenu. Must be rendered inside ContextMenuSub. Includes a trailing ArrowChevronRight icon.

ContextMenuSubContent

ContextMenuSubContent — the component that pops out when a submenu is open. Must be rendered inside ContextMenuSub.

Accessibility

Uses roving tabindex to manage focus among menu items. Use ContextMenuLabel (optionally inset) to title sections when needed, and avoid relying only on shortcut text for essential information.

Keyboard interactions

For the full primitive reference and any upstream updates, see Radix UI — Context Menu.

Implementation: packages/experience-system/src/components/ContextMenu/ContextMenu.tsx. Codegen-oriented rules for AI agents: packages/experience-system/src/components/ContextMenu/ContextMenu_instructions.md.