Prepared Docs

Overview

ContextMenu surfaces actions tied to a specific element via secondary-click or long-press. It speeds expert workflows on dense data but is invisible until invoked, so every action inside it must also be reachable through a visible path—row actions, a kebab menu, a toolbar, or a command palette. Platform guidance is unambiguous here: the context menu is an accelerator, never the only way to do something.

Right-click target

Incident

Flag for QA

Copy CAD ID

Delete comment

When to use

Dense data surfaces (tables, timelines, map features) where right-click on a row or marker is a learned shortcut.
Advanced actions that would overwhelm a primary toolbar but still matter to specialists.
Selection-aware menus where the context targets the currently selected row or region.

When not to use

Primary affordance for an action—use a visible Button, IconButton, or Menu trigger.
Mobile-only layouts without a parallel gesture affordance or a visible overflow menu.
Very deep trees of commands. Prefer staged dialogs or a dedicated inspector panel.

Content guidelines

Verb-first labels, title case per button and menu convention. formatMessage everywhere.
Destructive items sit in their own section at the bottom with separators and clear wording.
Submenus should be shallow. Each level adds motor and cognitive cost.

Reordering items

sortable on ContextMenu or NavigableContextMenu lets operators reorder items by drag or keyboard when order should persist (for example column lists). Use stable sortableId values on each item and handle onReorder. Every reorderable action must still be reachable outside the context menu—do not rely on right-click alone.

Behavior and states

Panel width while scrolling. When content exceeds the 40vh max height, root context menu panels apply a --overflow modifier that reserves space for a vertical scrollbar (scrollbar-gutter: stable with a narrow themed track). Short menus that fit within the panel do not show an empty gutter. While scrolling, the panel does not widen or shift horizontally.
Disabled items with explanations. Provide a reason in a tooltip only when a non-context path also surfaces the explanation—otherwise the reason is invisible to context-menu-only users.
Stale state on reopen. Refresh disabled flags and counts when the underlying data changes; don't let a reopened menu show yesterday's options.
Close on selection. Always close after a selection; destructive flows confirm in a separate dialog.

Best practices

Duplicate every critical command in row actions, kebab menus, or the command palette.
Keep menus shallow; prefer a single submenu over five levels.

Don't

Rely on context menus as training wheels for incomplete information architecture.
Pack dozens of unrelated commands into one root menu.

Accessibility

Provide keyboard-accessible alternatives to the gesture—an explicit Menu trigger, a documented shortcut, or both. Screen reader users may not discover context menus at all, so this parallel path is non-negotiable. See Accessibility for the full contract.

For sortable context menus, use Shift+Space or Shift+Enter on a focused row to begin keyboard reordering. Assign unique sortableId values when labels can repeat; duplicate identifiers and collapsible groups, including fragment-wrapped groups, disable sorting.

Menu for left-click dropdowns.
Toolbar for visible contextual strips.
Data table for row-action patterns.

Command / Accessibility

Context Menu / API and Development

Overview

Right-click target

Incident

Flag for QA

Copy CAD ID

Delete comment

When to use

Dense data surfaces (tables, timelines, map features) where right-click on a row or marker is a learned shortcut.
Advanced actions that would overwhelm a primary toolbar but still matter to specialists.
Selection-aware menus where the context targets the currently selected row or region.

When not to use

Primary affordance for an action—use a visible Button, IconButton, or Menu trigger.
Mobile-only layouts without a parallel gesture affordance or a visible overflow menu.
Very deep trees of commands. Prefer staged dialogs or a dedicated inspector panel.

Content guidelines

Verb-first labels, title case per button and menu convention. formatMessage everywhere.
Destructive items sit in their own section at the bottom with separators and clear wording.
Submenus should be shallow. Each level adds motor and cognitive cost.

Reordering items

Behavior and states

Panel width while scrolling. When content exceeds the 40vh max height, root context menu panels apply a --overflow modifier that reserves space for a vertical scrollbar (scrollbar-gutter: stable with a narrow themed track). Short menus that fit within the panel do not show an empty gutter. While scrolling, the panel does not widen or shift horizontally.
Disabled items with explanations. Provide a reason in a tooltip only when a non-context path also surfaces the explanation—otherwise the reason is invisible to context-menu-only users.
Stale state on reopen. Refresh disabled flags and counts when the underlying data changes; don't let a reopened menu show yesterday's options.
Close on selection. Always close after a selection; destructive flows confirm in a separate dialog.