Overlays & Actions
Context Menu
Context menu opens at the pointer on right-click (fine pointer) or long-press ~500ms (touch). Content is portaled with fixed positioning, outside-click / Escape dismiss, and submenu hover/click like shadcn. Reveal the right amount of context without losing the user's place in the interface. Keep the trigger, content and dismissal behavior working as one interaction. Import it from @/components/kamod-ui/context-menu.
Source · Design reference · API reference · Theming · Styles
Installation
Import primitives from @/components/kamod-ui/context-menu. Compose ContextMenu, ContextMenuTrigger, and ContextMenuContent; add ContextMenuGroup, ContextMenuItem, ContextMenuShortcut, ContextMenuSeparator, ContextMenuSub*, checkbox and radio items as needed.
pnpm add @kamod-ch/uiCopy an example with @kamod-ch/ui or the matching @kamod-ch/ui/… subpath. The code block switches between those two installs. Connect The Global Theme CSS and Tailwind Source Detection before your first render.
Usage
Optional controlled root: open, defaultOpen, onOpenChange. ContextMenuItem closes the menu on activate; checkbox/radio/sub-triggers do not. Use pointer-fine: / pointer-coarse: on the trigger hint text (see examples). Subpanels use absolute placement with RTL chevron flip.
import { ContextMenu } from "@kamod-ch/ui";Choose a complete composition from the examples below; required child components and props vary by pattern.
Component Examples & Variants
Explore Context Menu in Different Contexts, from the starting pattern to the compositions below. Begin with Combined Demo, then compare the examples that match your content, state and layout. These are working patterns to adapt, not a list of interchangeable variant values: check the API Reference before using a prop or combining behaviors. Look at the surrounding labels, supporting text and spacing as well as the component itself.
Read the Result and Its Implementation Together. Use each showcase’s Code view to inspect imports and composition, or its Prompt view to prepare a setup or adaptation brief. Try the narrow preview and local theme controls before connecting real data, and use Reset to return an example to its initial state. Keep layout changes in class utilities where appropriate; follow the Component Styles Guide for hierarchy and the Theming Guide for shared surfaces and colors. The Accessibility Notes explain what to preserve when making those changes.
Combined Demo
Combine Commands without Obscuring Their Roles. Combine ordinary actions, submenus, checkbox items and a radio group inside one context menu. The example demonstrates their different roles: invoking an operation, revealing more actions, toggling a setting or choosing one value.
Keep common actions near the start and provide another discoverable entry point for essential functionality; right-click alone is not enough for every input method.
// See context-menu-doc.tsx — ContextMenuFullDemoPreviewBasic
Start with a Short, Contextual Action List. Start with a small ContextMenu action group attached to a clearly identifiable target. This keeps the relationship between the selected content and the available commands easy to understand before adding nested or stateful options.
Avoid placing unrelated global navigation here, and ensure the same important operations remain reachable from an ordinary visible control.
Shortcuts
Use Key Hints as Accurate Documentation. Use ContextMenuShortcut for a trailing keyboard hint that stays visually separate from the action label. Keep the hint consistent with the shortcut your application implements; displaying it does not register a key handler.
Keep hints synchronized with registered actions and platform conventions, and avoid implying that a command works while its contextual target is unavailable.
Groups
Use Headings to Explain Relationships. Use ContextMenuLabel to name a section and ContextMenuSeparator between distinct action groups. A small amount of structure can make a longer menu readable without assigning every operation its own submenu.
Keep groups small and meaningful, and avoid decorative separators between every item when spacing and clear labels already provide enough structure.
Icons
Support Recognition without Replacing Labels. Place a supporting icon before each menu label, reserving destructive styling for the operation with that consequence. The icons reinforce recognizable actions, while the text remains sufficient to choose the correct command.
Treat decorative icons as hidden from assistive technology and keep destructive meaning explicit in the label rather than relying on an icon or color alone.
Checkboxes
Expose Persistent Independent Preferences. Use ContextMenuCheckboxItem for an independent on/off setting, with defaultChecked for initial state or checked and onCheckedChange for parent-owned state. Its checkmark represents a persistent choice rather than a one-time action.
Connect checked state to the application's actual preference source, and decide whether it persists beyond the current page; reopening the menu should accurately reflect the latest value.
Radio
Choose One Value from a Related Set. Use ContextMenuRadioGroup with value and onValueChange for mutually exclusive choices. Each item's value identifies one option, and the group's selected value remains the single source of truth for the setting.
Use stable values, keep the selected option consistent with the visible result, and ensure the group label explains what changing that choice affects.
Destructive
Keep Risky Commands Unmistakable. Set variant="destructive" on the context-menu item that performs a dangerous operation. Keep its label specific, and use the application's confirmation or recovery flow to handle the consequence beyond the menu itself.
The styling does not perform confirmation; compose Alert Dialog or offer undo according to the application's recovery model.
Props and Data
Configure Context Menu using the contracts below. Read the documented options alongside the Source Definitions to understand which values your application supplies and which details the component owns. Start with a prop or helper, then follow its type link to inspect the declaration without leaving the page.
Props, slots and variants for this component.
Type cards are extracted from this checkout’s TypeScript source at build time. Props inherited through HTMLAttributes, Omit or variant helpers remain references in those declarations; their fields are not flattened here. Match the reference to your installed version, and check a package’s exports before writing an import type. A type exported by a source file is not necessarily re-exported by @kamod-ch/ui.
Component Props
? means a field can be omitted; it does not promise a fallback value. Existing documented defaults remain alongside the descriptions. For callbacks, check the argument and return types before connecting your own state or services.Data Type Reference
Expand a card to inspect and copy the exact declaration. The code header identifies its repository file; follow imported or inherited types in the Implementation Source when you need the complete dependency chain. Required-field summaries cover fields declared directly in that type. Source-only helpers and inferred schema outputs describe the local implementation, not additional props you can pass to every component.
ContextMenuPoint
2 declared fieldsContextMenuPointContextMenu.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuPoint before adapting it.x, yContextMenuContextValue
6 declared fieldsContextMenuContextValueContextMenu.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuContextValue before adapting it.open, setOpen, position, setPosition, contentWrapperRef, triggerRefContextMenu Props
4 declared fieldsContextMenuPropsContextMenu.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuProps before adapting it.ContextMenuCheckboxItem Props
4 declared fieldsContextMenuCheckboxItemPropsContextMenuCheckboxItem.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuCheckboxItemProps before adapting it.ContextMenuContent Props
1 declared fieldContextMenuContentPropsContextMenuContent.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuContentProps before adapting it.ContextMenuGroup Props
1 declared fieldContextMenuGroupPropsContextMenuGroup.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuGroupProps before adapting it.ContextMenuItem Props
1 declared fieldContextMenuItemPropsContextMenuItem.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuItemProps before adapting it.ContextMenuLabel Props
2 declared fieldsContextMenuLabelPropsContextMenuLabel.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuLabelProps before adapting it.ContextMenuRadioGroup Props
4 declared fieldsContextMenuRadioGroupPropsContextMenuRadioGroup.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuRadioGroupProps before adapting it.ContextMenuRadioItem Props
2 declared fieldsContextMenuRadioItemPropsContextMenuRadioItem.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuRadioItemProps before adapting it.valueContextMenuSeparator Props
DeclarationContextMenuSeparatorPropsContextMenuSeparator.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuSeparatorProps before adapting it.ContextMenuShortcut Props
1 declared fieldContextMenuShortcutPropsContextMenuShortcut.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuShortcutProps before adapting it.ContextMenuSub Props
1 declared fieldContextMenuSubPropsContextMenuSub.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuSubProps before adapting it.ContextMenuSubContent Props
1 declared fieldContextMenuSubContentPropsContextMenuSubContent.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuSubContentProps before adapting it.ContextMenuSubTrigger Props
1 declared fieldContextMenuSubTriggerPropsContextMenuSubTrigger.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuSubTriggerProps before adapting it.ContextMenuTrigger Props
1 declared fieldContextMenuTriggerPropsContextMenuTrigger.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuTriggerProps before adapting it.ContextMenuRadioContextValue
2 declared fieldsContextMenuRadioContextValuecontext-menu-radio-context.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuRadioContextValue before adapting it.value, setValueContextMenuSubContextValue
4 declared fieldsContextMenuSubContextValuecontext-menu-sub-context.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ContextMenuSubContextValue before adapting it.open, setOpen, markFocusOnOpen, consumeFocusOnOpenAccessibility
Build the Complete Interaction, Including the Parts Outside Context Menu. The notes below distinguish the current implementation from the labels, content and behavior your application supplies. Start with the Live Preview, check the Props and Data Reference, and test the finished composition with real content rather than assuming that an unchanged visual example covers every use case.
Built-in Behavior and Defaults
ContextMenu uses menu and menuitem semantics, including checkbox/radio variants and submenus. Escape closes the root menu. A context menu is an additional way to reach actions, not a sufficient primary interface by itself.
Labels and Relationships
Name each action by its outcome and make its target clear. If multiple items expose the same menu, ensure the action context identifies the selected file, row or object rather than operating on an unexpected prior selection.
Keyboard and Focus
Test the platform keyboard context-menu gesture as well as right-click. Provide a visible Actions button or equivalent path when the trigger composition does not support keyboard invocation. Keep dismissal and return focus predictable.
States and Integration Details
Touch and assistive-technology users may never discover a right-click-only action. Do not suppress the browser context menu broadly across unrelated content, and do not rely on pointer position to identify the action target after focus changes.
Verify the Complete Interaction
Check Behavior as Well as Markup. Work through these scenarios in the application where the component will be used. Automated checks can help find structural problems; also review the reading experience with a screen reader, keyboard focus and the actual feedback from your application.
- Perform every essential action through a visible keyboard-operable alternative.
- Open the menu for different objects and verify action targets and checked states.
- Dismiss submenus and the root menu and confirm focus remains associated with the intended object.
Recheck the result after changing Theme Tokens, translations or class overrides. Include text enlargement, narrow layouts and reduced-motion settings where animation is present. Inspect the Component Source when a behavior differs from your expectation; a role or state attribute does not implement keyboard interaction by itself.
For background, read the WAI-ARIA Authoring Guidance and Keyboard Interface Guidance. These explain the patterns; verify browser and assistive-technology behavior for the implementation and audience you actually support.
You have the pieces. Put them into one real interaction, keep its state in one place, and check the result with the content your application will actually show.
Connect the Foundation
Return to Choose and Compose Components to connect this reference to a working screen. Keep global CSS in one entrypoint and import only the components that screen needs.
Build the Surrounding Screen
Find a neighboring interaction in the Component Library, or start with a complete Block. Replace sample content and destinations before refining the layout; a local class change can stay with the composition.
Make the Result Hold Up
Use shared theme roles for changes that belong everywhere. Then review the whole journey: keyboard focus, long labels, narrow screens and a clear way to recover when something fails.
Keep a link to the source and note your intentional changes. Your next edit should begin with a clear decision, not another search.