ContextMenu·component·@astryxdesign/core

Context Menu

A context menu that appears on right-click at the cursor position. Wraps trigger content as children.

Open in Playground @astryxdesign/core/ContextMenu

Showcases and examples

3 documented examples

Context Menu

An adaptive context area that supports long-press on compact touch screens and right-click elsewhere.

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · context-menu-showcase

// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';

import {ContextMenu} from '@astryxdesign/core/ContextMenu';

export default function ContextMenuShowcase() {
  return (
    <ContextMenu
      presentation="adaptive"
      items={[
        {label: 'Cut', onClick: () => {}},
        {label: 'Copy', onClick: () => {}},
        {label: 'Paste', onClick: () => {}},
      ]}>
      <div
        style={{
          padding: '48px',
          borderWidth: '2px',
          borderStyle: 'dashed',
          borderColor: '#d1d5db',
          borderRadius: '8px',
          textAlign: 'center',
          color: '#6b7280',
          userSelect: 'none',
        }}>
        Long-press or right-click this area
      </div>
    </ContextMenu>
  );
}

Usage

A right-click context menu that appears at the cursor position. Use to provide contextual actions for specific elements or regions without cluttering the UI with visible buttons.

Keep menu items concise and action-oriented; users expect quick access to contextual actions.
Use sections and dividers to group related actions when the menu has many items.
Use presentation="adaptive" when right-click should remain cursor-positioned on desktop while long-press opens a reachable BottomSheet on compact touch devices.
Ensure all context menu actions are also accessible via other UI elements for keyboard-only users.
Keep a visible MoreMenu or equivalent trigger for important mobile actions; long-press must not be the only route.
Use a ContextMenu as the only way to access important actions; not all users know to right-click.
Place more than 10–12 items in a single menu without grouping them into sections.

Typed props

Prop	Type and behavior
`children`	`ReactNode` · required The trigger area: right-click on this content to open the menu.
`items`	`ContextMenuOption[]` · required Array of menu entries. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?, variant?, items?}` (nested `items` open a flyout in popover presentation and drill into a new view in bottom-sheet presentation; variant `"destructive"` renders it in the error color), a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.
`menuContent`	`ReactNode` Custom JSX menu content for compound mode. Use instead of items for dynamic or stateful menus.
`menuWidth`	`number \| string` · default '160px' Custom menu width.
`size`	`'sm' \| 'md' \| 'lg'` · default 'md' Size of menu items: controls padding density.
`label`	`string` · default 'Context menu' Accessible name for the menu surface, announced when it opens.
`onOpenChange`	`(isOpen: boolean) => void` Callback fired when the menu opens or closes.
`presentation`	`'popover' \| 'bottom-sheet' \| 'adaptive'` · default 'popover' Presentation policy. `popover` opens at the pointer position, `bottom-sheet` always uses an action sheet, and `adaptive` uses the BottomSheet at 768px and below when the primary pointer is coarse.
`isDisabled`	`boolean` · default false When true, right-click shows the native browser context menu instead.

Anatomy

Trigger area · required

Caller-provided region that accepts right-click, keyboard context-menu, and long-press input.

Pointer menu surface · optional

Cursor-positioned menu panel used by the pointer presentation.

Pointer action row · optional

DropdownMenu-owned action, selectable option, or submenu row in the pointer presentation.

Touch sheet frame · optional

BottomSheet panel, content area, handle, and optional scrim that host touch actions.

Touch menu surface · optional

ContextMenu-owned content panel rendered inside the touch sheet frame.

Touch action list · optional

Spacious List that groups data-driven touch actions.

Touch action row · optional

ListItem button used for a data-driven action or drill-in entry in the touch presentation.

Theming

Targets

astryx-context-menu

Variables

--_dropdown-menu-radius · private

Border radius of the menu popup

Default: var(--radius-container)

--_dropdown-menu-padding · private

Inner padding of the menu popup

Default: var(--spacing-1)

Derived properties

borderRadius

Uses --_dropdown-menu-radius.

padding

Uses --_dropdown-menu-padding.