Skip to main content

Starwind UI v3.0 is now available! Migration guide

Context Menu

Installation

Usage

---
import {
ContextMenu,
ContextMenuCheckboxItem,
ContextMenuContent,
ContextMenuGroup,
ContextMenuItem,
ContextMenuSeparator,
ContextMenuShortcut,
ContextMenuSub,
ContextMenuSubContent,
ContextMenuSubTrigger,
ContextMenuTrigger,
} from "@/components/starwind/context-menu";
---
<ContextMenu>
<ContextMenuTrigger class="flex aspect-video w-full min-w-40 max-w-xs items-center justify-center rounded-xl border border-dashed text-sm">
<span class="hidden pointer-fine:inline-block">Right click here</span>
<span class="hidden pointer-coarse:inline-block">Long press here</span>
</ContextMenuTrigger>
<ContextMenuContent class="w-48">
<ContextMenuGroup>
<ContextMenuItem>
Back
<ContextMenuShortcut>⌘[</ContextMenuShortcut>
</ContextMenuItem>
<ContextMenuItem disabled>
Forward
<ContextMenuShortcut>⌘]</ContextMenuShortcut>
</ContextMenuItem>
<ContextMenuItem>
Reload
<ContextMenuShortcut>⌘R</ContextMenuShortcut>
</ContextMenuItem>
<ContextMenuSub>
<ContextMenuSubTrigger>More Tools</ContextMenuSubTrigger>
<ContextMenuSubContent class="w-44">
<ContextMenuGroup>
<ContextMenuItem>Save Page...</ContextMenuItem>
<ContextMenuItem>Create Shortcut...</ContextMenuItem>
<ContextMenuItem>Name Window...</ContextMenuItem>
</ContextMenuGroup>
<ContextMenuSeparator />
<ContextMenuGroup>
<ContextMenuItem>Developer Tools</ContextMenuItem>
</ContextMenuGroup>
<ContextMenuSeparator />
<ContextMenuGroup>
<ContextMenuItem class="text-destructive data-highlighted:text-destructive focus:text-destructive">Delete</ContextMenuItem>
</ContextMenuGroup>
</ContextMenuSubContent>
</ContextMenuSub>
</ContextMenuGroup>
<ContextMenuSeparator />
<ContextMenuGroup>
<ContextMenuCheckboxItem defaultChecked>Show Bookmarks</ContextMenuCheckboxItem>
<ContextMenuCheckboxItem>Show Full URLs</ContextMenuCheckboxItem>
</ContextMenuGroup>
</ContextMenuContent>
</ContextMenu>

Composition

Use the following composition to build a ContextMenu:

ContextMenu
├── ContextMenuTrigger
└── ContextMenuContent
├── ContextMenuGroup
│ ├── ContextMenuLabel
│ ├── ContextMenuItem
│ └── ContextMenuCheckboxItem
├── ContextMenuSeparator
└── ContextMenuSub
├── ContextMenuSubTrigger
└── ContextMenuSubContent
└── ContextMenuGroup
├── ContextMenuItem
└── ContextMenuItem

Basic

A simple context menu with a few actions.

Use ContextMenuSub, ContextMenuSubTrigger, and ContextMenuSubContent to nest secondary actions.

Shortcuts

Add ContextMenuShortcut to show keyboard hints.

With Icons

Combine icons with labels for quick scanning.

Checkboxes

Use ContextMenuCheckboxItem for toggle actions.

API Reference

Styled Component API

These props are added or materially changed by the installed styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Expand a prop to see named type definitions and framework-specific imports. Follow the Primitive and Runtime links for lower-level behavior props.

Context Menu Content

Inherits div attributes.

Contains the following additional props:

Prop Type Default Toggle details
disablePortal boolean false
Description
Keeps the public Portal wrapper inline instead of moving it to a target.
Classification
Wrapper prop
portalContainer string —
Description
Sets the CSS selector for the public Portal wrapper target.
Classification
Wrapper prop

Context Menu Item

Inherits div attributes.

Contains the following additional props:

Prop Type Default Toggle details
inset boolean false
Description
Adds leading inset spacing for visual alignment.
Classification
Wrapper prop

Context Menu Checkbox Item

Inherits div attributes. Omits `aria-checked` and `role`.

Contains the following additional props:

Prop Type Default Toggle details
closeOnClick boolean false
Description
Closes the containing surface after the item is activated.
Classification
Wrapper prop
indicatorClass string —
Description
Adds classes to the generated selection indicator.
Classification
Wrapper prop
inset boolean false
Description
Adds leading inset spacing for visual alignment.
Classification
Wrapper prop
showIndicator boolean true
Description
Shows the generated selection indicator.
Classification
Wrapper prop

Context Menu Radio Item

Inherits div attributes. Omits `aria-checked` and `role`.

Contains the following additional props:

Prop Type Default Toggle details
closeOnClick boolean false
Description
Closes the containing surface after the item is activated.
Classification
Wrapper prop
indicatorClass string —
Description
Adds classes to the generated selection indicator.
Classification
Wrapper prop
inset boolean false
Description
Adds leading inset spacing for visual alignment.
Classification
Wrapper prop
showIndicator boolean true
Description
Shows the generated selection indicator.
Classification
Wrapper prop
value Required string —
Description
Controls or identifies the component value.
Classification
Wrapper prop

Context Menu Label

Inherits div attributes.

Contains the following additional props:

Prop Type Default Toggle details
inset boolean false
Description
Adds leading inset spacing for visual alignment.
Classification
Wrapper prop

Context Menu Sub Trigger

Inherits div attributes.

Contains the following additional props:

Prop Type Default Toggle details
inset boolean false
Description
Adds leading inset spacing for visual alignment.
Classification
Wrapper prop

Context Menu Sub Content

Inherits div attributes.

Contains the following additional props:

Prop Type Default Toggle details
disablePortal boolean false
Description
Keeps the public Portal wrapper inline instead of moving it to a target.
Classification
Wrapper prop
portalContainer string —
Description
Sets the CSS selector for the public Portal wrapper target.
Classification
Wrapper prop
side "top" | "right" | "bottom" | "left" "right"
Description
Selects the preferred side for floating content.
Classification
Primitive override
Primitive prop
context-menu.Popup.side
sideOffset number 0
Description
Sets the distance in pixels between floating content and its anchor.
Classification
Primitive override
Primitive prop
context-menu.Popup.sideOffset

Primitive And Runtime API

Use these references when you need the lower-level behavior APIs behind Context Menu.

Runtime API

Context Menu primitive
createContextMenu from @starwind-ui/runtime/context-menu

Changelog

View version history v2.3.0 6 releases

v2.3.0

  • In Svelte, a defined open, an item’s checked, or a radio group’s value that you pass when ContextMenu mounts now stays under your control, as in React and Vue. To change it, use bind: or update your state in the change callback. A form reset keeps it. If you pass undefined at mount, ContextMenu keeps its own state.
  • In Vue, a Boolean prop that you leave out, such as checked on a checkbox or radio item, no longer becomes false. The default of the underlying component applies.
  • Fixed a ContextMenu trigger on a link or span that stayed disabled when a framework wrote disabled="false". On a native form control, any disabled attribute still disables it.

v2.2.0

  • Vue checkbox and radio menu items keep their previous selection when a change is canceled.
  • Added an optional icon slot to submenu triggers across frameworks.
  • Fixed an open menu jumping away from where it was opened when the component updates.
  • Reduced background work when a React page uses multiple menus, tooltips, or other portals.
  • Fixed nested Svelte overlays inside a dialog appearing behind their parent or failing to receive clicks.
  • Fixed nested overlays appearing behind their parent in Vue and Svelte. Overlays can now render under the document body; if custom CSS or DOM queries require them to stay inside a parent, set a portal container or add data-floating-root to that parent.
  • Fixed React 18 retaining removed popup elements when the parent component stays mounted.

v2.1.1

  • Group headings are now linked to their groups with aria-labelledby, so screen readers announce the name of each group.

v2.1.0

  • Added portalContainer and disablePortal to ContextMenuContent and ContextMenuSubContent for custom portal targets and inline rendering.
  • On touch screens, a parent menu now stays open while focus moves into a submenu, so the submenu stays next to its trigger.

v2.0.1

  • The default export in index.ts now has a name, ContextMenuParts, so framework tools show a clear name.

v2.0.0

  • Context Menu now gets its behavior from Starwind Runtime. Runtime handles opening, keyboard navigation, submenus, and checked items.
  • See the Context Menu Primitive for the unstyled parts and the behavior API.