ContextMenu

Menu of actions or options, opened by right-clicking (or long-pressing) its trigger surface. Supports nested submenus, checkbox/radio items, separators, and keyboard shortcuts. Open state is uncontrolled by default; pass onOpenChange to observe it.

Usage

import { ContextMenu, contextMenuAnatomy, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger } from "@instruments/materia-ui/components/context-menu";

Best practices

Use ContextMenu for a right-click / long-press menu on a surface; a menu opened by clicking a button or trigger is a DropdownMenu.
Wrap the target region in ContextMenuTrigger so the whole surface is right-clickable; use ContextMenuCheckboxItem / ContextMenuRadioGroup for stateful rows.

Props

ContextMenuCheckboxItem

Prop	Type	Description
className	`string`
render	`useRender.RenderProp<Record<string, unknown>> \| undefined`	Replace the default `<button>` row; glyph props render inside it, around `children`.
children	`string \| number \| React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>`	Text label. Use `icon` prop for icons, not children.

ContextMenuContent

Prop	Type	Description
className	`string`
size	`"base" \| "2xs" \| "xs" \| "sm" \| "lg" \| "xl" \| "2xl" \| "3xl"`
itemRadius	`"rounded" \| "square" \| "full"`	Border radius for menu items. When "full", items become pill-shaped.
surface	`MenuSurface`	Surface density. Compact maps to the 16px-radius, 4px-padding menu surface.
contentWidth	`MenuContentWidth`	Named content widths from the design system.
overflow	`MenuOverflow`	Outer content overflow behaviour. Use hidden when a child owns scrolling.

ContextMenuItem

Prop	Type	Description
className	`string`
inset	`boolean`
tone	`"neutral" \| "danger"`
avatar	`React.ReactNode`
dot	`boolean \| "neutral" \| "brand" \| "danger" \| "warning" \| "success" \| "info"`	Dot indicator at the start (takes precedence over icon): `true` for a neutral dot, or a {@link Tone} to tint it.
icon	`LucideIcon \| React.ComponentType<React.SVGProps<SVGSVGElement>>`
suffixIcon	`LucideIcon \| React.ComponentType<React.SVGProps<SVGSVGElement>>`
kbd	`string[]`
suffix	`React.ReactNode`
active	`boolean`	Whether the item is in an active/selected state
activeIndicator	`"none" \| "dot" \| "check"`	Visual indicator for active state. "dot" shows grey dot normally, green when active. "check" shows green checkmark only when active.
render	`useRender.RenderProp<Record<string, unknown>> \| undefined`	Replace the default `<button>` row (e.g. with a link); glyph props render inside it, around `children`.
children	`string \| number \| React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>`	Text label. Use `icon` prop for icons, not children.

ContextMenuLabel

Prop	Type	Default	Description
className	`string`
inset	`boolean`

ContextMenuRadioItem

Prop	Type	Description
className	`string`
render	`useRender.RenderProp<Record<string, unknown>> \| undefined`	Replace the default `<button>` row; glyph props render inside it, around `children`.
children	`string \| number \| React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>`	Text label. Use `icon` prop for icons, not children.

ContextMenuSeparator

Prop	Type	Default	Description
className	`string`
spacing	`"default" \| "compact"`

ContextMenuSubContent

Prop	Type	Default	Description
className	`string`
size	`"base" \| "2xs" \| "xs" \| "sm" \| "lg" \| "xl" \| "2xl" \| "3xl"`

ContextMenuSubTrigger

Prop	Type	Description
className	`string`
render	`useRender.RenderProp<Record<string, unknown>> \| undefined`	Replace the default `<button>` row; glyph props render inside it, around `children`.
children	`string \| number \| React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>`	Text label. Use `icon` prop for icons, not children.
inset	`boolean`
icon	`LucideIcon \| React.ComponentType<React.SVGProps<SVGSVGElement>>`

Also exports

componentContextMenu
constcontextMenuAnatomy
componentContextMenuGroup
componentContextMenuPortal
componentContextMenuRadioGroup
componentContextMenuShortcut
componentContextMenuSub
componentContextMenuTrigger

Anatomy

ContextMenu

context-menu

Context menu triggered by right-click on a surface

ContextMenuTrigger

context-menu-trigger

Surface that opens menu on right-click

ContextMenuContent

context-menu-content

Menu content container

ContextMenuItem

context-menu-item

Menu item

ContextMenuCheckboxItem

context-menu-checkbox-item

Toggleable item

ContextMenuRadioGroup

context-menu-radio-group

Exclusive selection group

ContextMenuRadioItem

context-menu-radio-item

Radio option

ContextMenuLabel

context-menu-label

Section label

ContextMenuSeparator

context-menu-separator

Visual divider

ContextMenuSub

context-menu-sub

Nested submenu

ContextMenuSubTrigger

context-menu-sub-trigger

Opens nested menu

ContextMenuSubContent

context-menu-sub-content

Nested menu container

ContextMenuShortcut

context-menu-shortcut

Keyboard shortcut

Composition

Builds on

Icon, MenuItem