ContextMenu Primitive
ContextMenu is a Starwind Runtime primitive in the composite-menu-overlay contract family.
Anatomy
Use the Astro primitive adapter to render ContextMenu anatomy with the Runtime wiring included.
---import { ContextMenu } from "@starwind-ui/astro/context-menu";---
<ContextMenu.Root> <ContextMenu.Trigger>Right click</ContextMenu.Trigger> <ContextMenu.Positioner> <ContextMenu.Popup> <ContextMenu.Item>Copy</ContextMenu.Item> </ContextMenu.Popup> </ContextMenu.Positioner></ContextMenu.Root>Use the React primitive adapter when ContextMenu state participates in React rendering.
import { ContextMenu } from "@starwind-ui/react/context-menu";
export function Example() { return ( <ContextMenu.Root> <ContextMenu.Trigger>Right click</ContextMenu.Trigger> <ContextMenu.Positioner> <ContextMenu.Popup> <ContextMenu.Item>Copy</ContextMenu.Item> </ContextMenu.Popup> </ContextMenu.Positioner> </ContextMenu.Root> );}Render the ContextMenu data-sw-* contract yourself, then initialize createContextMenu.
<div data-sw-context-menu data-sw-menu=""> <div data-sw-context-menu-trigger data-sw-menu-trigger="" aria-haspopup="menu">Right click</div> <div data-sw-menu-positioner> <div data-sw-menu-popup role="menu" tabindex="-1" hidden> <div data-sw-menu-item role="menuitem" tabindex="0">Copy</div> </div> </div></div>
<script type="module"> import { createContextMenu } from "@starwind-ui/runtime/context-menu";
const root = document.querySelector("[data-sw-context-menu]"); if (root) { createContextMenu(root); }</script>Floating Behavior
| Fact | Value |
|---|---|
| Anchor part | anchor |
| Positioner part | positioner |
| Popup part | popup |
| Portal part | portal |
| Option props | side, align, sideOffset, avoidCollisions |
API Reference
Root
The main element that owns the ContextMenu Runtime instance.
- Default element
- div
- Discovery hook
- data-sw-context-menu
- Role
- -
Props
open boolean -
- Description
- Controls whether ContextMenu is open.
- Kind
- control
- Targets
- root
- Full type
- boolean
defaultOpen boolean false
- Description
- Sets whether ContextMenu starts open.
- Kind
- control
- Targets
- root
- Full type
- boolean
disabled boolean false
- Description
- Disables the Root part.
- Kind
- option
- Targets
- root, trigger, item, linkItem, checkboxItem, radioItem, submenuTrigger
- Full type
- boolean
modal boolean true
- Description
- Makes ContextMenu behave as a modal overlay.
- Kind
- option
- Targets
- root
- Full type
- boolean
closeDelay number 200
- Description
- Sets how long ContextMenu waits before closing.
- Kind
- option
- Targets
- root, submenuRoot
- Full type
- number
onCloseComplete (open: boolean, details: ContextMenuCloseCompleteDetails) => void -
- Description
- Runs after ContextMenu has finished closing.
- Kind
- callback
- Targets
- root
- Full type
- (open: boolean, details: ContextMenuCloseCompleteDetails) => void
onOpenChange (open: boolean, details: ContextMenuOpenChangeDetails) => void -
- Description
- Runs when ContextMenu opens or closes.
- Kind
- callback
- Targets
- root
- Full type
- (open: boolean, details: ContextMenuOpenChangeDetails) => void
Events
openChange onOpenChange open: boolean
- Description
- Fires when ContextMenu opens or closes.
- DOM event
- starwind:open-change
- Details type
- ContextMenuOpenChangeDetails
- Timing
- before-state-commit
- Cancelable
- Yes
closeComplete onCloseComplete open: boolean
- Description
- Fires after ContextMenu has finished closing.
- DOM event
- starwind:close-complete
- Details type
- ContextMenuCloseCompleteDetails
- Timing
- after-state-commit
- Cancelable
- No
State
open boolean open / defaultOpen
- Description
- Tracks whether ContextMenu is open.
- Initial attribute
- data-default-open
- Runtime getter
- getOpen
- Runtime setter
- setOpen
- State control support
- React supports controlled and default state with open and defaultOpen props. Runtime/HTML reads initial state from data-default-open, emits starwind:open-change and starwind:close-complete, and updates with setOpen. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state.
checked boolean checked / defaultChecked
- Description
- Tracks whether ContextMenu is checked.
- Initial attribute
- data-default-checked
- Runtime getter
- -
- Runtime setter
- -
- State control support
- React supports controlled and default state with checked and defaultChecked props. Runtime/HTML reads initial state from data-default-checked and emits starwind:checked-change. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state.
radioValue string value / defaultValue
- Description
- Tracks the selected radio value for ContextMenu.
- Initial attribute
- data-value
- Runtime getter
- -
- Runtime setter
- -
- State control support
- React supports controlled and default state with value and defaultValue props. Runtime/HTML reads initial state from data-value and emits starwind:value-change. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state.
Data Attributes
Runtime hooks
State
Metadata
Trigger
The control that opens, closes, or targets the ContextMenu content.
- Default element
- div
- Discovery hook
- data-sw-context-menu-trigger
- Role
- -
Props
disabled boolean false
- Description
- Disables the Trigger part.
- Kind
- option
- Targets
- root, trigger, item, linkItem, checkboxItem, radioItem, submenuTrigger
- Full type
- boolean
Data Attributes
Runtime hooks
State
Metadata
Anchor
The virtual anchor used to position ContextMenu content.
- Default element
- span
- Discovery hook
- data-sw-context-menu-anchor
- Role
- -
Data Attributes
Runtime hooks
Portal
Moves ContextMenu overlay content to the document body when needed.
- Default element
- div
- Discovery hook
- data-sw-menu-portal
- Role
- -
Data Attributes
Runtime hooks
Positioner
Positions the ContextMenu content relative to its trigger.
- Default element
- div
- Discovery hook
- data-sw-menu-positioner
- Role
- -
Props
side "top" | "right" | "bottom" | "left" "bottom"
- Description
- Sets the preferred side for ContextMenu content.
- Kind
- option
- Targets
- positioner, popup
- Full type
- "top" | "right" | "bottom" | "left"
align "start" | "center" | "end" "start"
- Description
- Sets how ContextMenu content aligns to its trigger.
- Kind
- option
- Targets
- positioner, popup
- Full type
- "start" | "center" | "end"
sideOffset number 4
- Description
- Sets the distance between ContextMenu content and its trigger.
- Kind
- option
- Targets
- positioner, popup
- Full type
- number
avoidCollisions boolean true
- Description
- Allows ContextMenu content to shift or flip to stay visible.
- Kind
- option
- Targets
- positioner, popup
- Full type
- boolean
Data Attributes
Runtime hooks
State
Metadata
Popup
The floating content container for ContextMenu.
- Default element
- div
- Discovery hook
- data-sw-menu-popup
- Role
- menu
Props
side "top" | "right" | "bottom" | "left" "bottom"
- Description
- Sets the preferred side for ContextMenu content.
- Kind
- option
- Targets
- positioner, popup
- Full type
- "top" | "right" | "bottom" | "left"
align "start" | "center" | "end" "start"
- Description
- Sets how ContextMenu content aligns to its trigger.
- Kind
- option
- Targets
- positioner, popup
- Full type
- "start" | "center" | "end"
sideOffset number 4
- Description
- Sets the distance between ContextMenu content and its trigger.
- Kind
- option
- Targets
- positioner, popup
- Full type
- number
avoidCollisions boolean true
- Description
- Allows ContextMenu content to shift or flip to stay visible.
- Kind
- option
- Targets
- positioner, popup
- Full type
- boolean
Data Attributes
Runtime hooks
State
Metadata
Item
An interactive item inside the ContextMenu collection.
- Default element
- div
- Discovery hook
- data-sw-menu-item
- Role
- menuitem
Props
disabled boolean false
- Description
- Disables the Item part.
- Kind
- option
- Targets
- root, trigger, item, linkItem, checkboxItem, radioItem, submenuTrigger
- Full type
- boolean
closeOnClick boolean true
- Description
- Closes ContextMenu after the item is clicked.
- Kind
- option
- Targets
- item
- Full type
- boolean
Data Attributes
Runtime hooks
Metadata
Link Item
A link-style item inside the ContextMenu collection.
- Default element
- a
- Discovery hook
- data-sw-menu-link-item
- Role
- menuitem
Props
disabled boolean false
- Description
- Disables the Link Item part.
- Kind
- option
- Targets
- root, trigger, item, linkItem, checkboxItem, radioItem, submenuTrigger
- Full type
- boolean
closeOnClick boolean false
- Description
- Closes ContextMenu after the item is clicked.
- Kind
- option
- Targets
- linkItem
- Full type
- boolean
Data Attributes
Runtime hooks
Metadata
Checkbox Item
A checkbox-style item inside the ContextMenu collection.
- Default element
- div
- Discovery hook
- data-sw-menu-checkbox-item
- Role
- menuitemcheckbox
Props
disabled boolean false
- Description
- Disables the Checkbox Item part.
- Kind
- option
- Targets
- root, trigger, item, linkItem, checkboxItem, radioItem, submenuTrigger
- Full type
- boolean
checked boolean -
- Description
- Controls whether ContextMenu is checked.
- Kind
- control
- Targets
- checkboxItem, radioItem
- Full type
- boolean
defaultChecked boolean false
- Description
- Sets whether ContextMenu starts checked for uncontrolled usage.
- Kind
- control
- Targets
- checkboxItem, radioItem
- Full type
- boolean
closeOnClick boolean false
- Description
- Closes ContextMenu after the item is clicked.
- Kind
- option
- Targets
- checkboxItem, radioItem
- Full type
- boolean
onCheckedChange (checked: boolean, details: MenuCheckedChangeDetails) => void -
- Description
- Runs when the ContextMenu checked state changes.
- Kind
- callback
- Targets
- checkboxItem
- Full type
- (checked: boolean, details: MenuCheckedChangeDetails) => void
Events
checkedChange onCheckedChange checked: boolean
- Description
- Fires when the checked state changes for ContextMenu.
- DOM event
- starwind:checked-change
- Details type
- MenuCheckedChangeDetails
- Timing
- before-state-commit
- Cancelable
- Yes
State
checked boolean checked / defaultChecked
- Description
- Tracks whether ContextMenu is checked.
- Initial attribute
- data-default-checked
- Runtime getter
- -
- Runtime setter
- -
- State control support
- React supports controlled and default state with checked and defaultChecked props. Runtime/HTML reads initial state from data-default-checked and emits starwind:checked-change. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state.
Data Attributes
Runtime hooks
State
Metadata
Checkbox Item Indicator
Shows the checked state for a ContextMenu checkbox item.
- Default element
- span
- Discovery hook
- data-sw-menu-checkbox-item-indicator
- Role
- -
Data Attributes
Runtime hooks
State
Radio Group
Groups related radio items inside ContextMenu.
- Default element
- div
- Discovery hook
- data-sw-menu-radio-group
- Role
- group
Props
value string -
- Description
- Controls the current ContextMenu value.
- Kind
- control
- Targets
- radioGroup
- Full type
- string
defaultValue string -
- Description
- Sets the initial ContextMenu value for uncontrolled usage.
- Kind
- control
- Targets
- radioGroup
- Full type
- string
onValueChange (value: string, details: MenuValueChangeDetails) => void -
- Description
- Runs when the ContextMenu value changes.
- Kind
- callback
- Targets
- radioGroup
- Full type
- (value: string, details: MenuValueChangeDetails) => void
Events
valueChange onValueChange value: string
- Description
- Fires when the value changes for ContextMenu.
- DOM event
- starwind:value-change
- Details type
- MenuValueChangeDetails
- Timing
- before-state-commit
- Cancelable
- Yes
State
radioValue string value / defaultValue
- Description
- Tracks the selected radio value for ContextMenu.
- Initial attribute
- data-value
- Runtime getter
- -
- Runtime setter
- -
- State control support
- React supports controlled and default state with value and defaultValue props. Runtime/HTML reads initial state from data-value and emits starwind:value-change. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state.
Data Attributes
Runtime hooks
State
Radio Item
A radio-style item inside the ContextMenu collection.
- Default element
- div
- Discovery hook
- data-sw-menu-radio-item
- Role
- menuitemradio
Props
disabled boolean false
- Description
- Disables the Radio Item part.
- Kind
- option
- Targets
- root, trigger, item, linkItem, checkboxItem, radioItem, submenuTrigger
- Full type
- boolean
checked boolean -
- Description
- Controls whether ContextMenu is checked.
- Kind
- control
- Targets
- checkboxItem, radioItem
- Full type
- boolean
defaultChecked boolean false
- Description
- Sets whether ContextMenu starts checked for uncontrolled usage.
- Kind
- control
- Targets
- checkboxItem, radioItem
- Full type
- boolean
closeOnClick boolean false
- Description
- Closes ContextMenu after the item is clicked.
- Kind
- option
- Targets
- checkboxItem, radioItem
- Full type
- boolean
value string -
- Description
- Controls the current ContextMenu value.
- Kind
- option
- Targets
- radioItem
- Full type
- string
State
checked boolean checked / defaultChecked
- Description
- Tracks whether ContextMenu is checked.
- Initial attribute
- data-default-checked
- Runtime getter
- -
- Runtime setter
- -
- State control support
- React supports controlled and default state with checked and defaultChecked props. Runtime/HTML reads initial state from data-default-checked and emits starwind:checked-change. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state.
radioValue string value / defaultValue
- Description
- Tracks the selected radio value for ContextMenu.
- Initial attribute
- data-value
- Runtime getter
- -
- Runtime setter
- -
- State control support
- React supports controlled and default state with value and defaultValue props. Runtime/HTML reads initial state from data-value and emits starwind:value-change. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state.
Data Attributes
Runtime hooks
State
Metadata
Radio Item Indicator
Shows the selected state for a ContextMenu radio item.
- Default element
- span
- Discovery hook
- data-sw-menu-radio-item-indicator
- Role
- -
Data Attributes
Runtime hooks
State
Group
Groups related ContextMenu items.
- Default element
- div
- Discovery hook
- data-sw-menu-group
- Role
- group
Data Attributes
Runtime hooks
Label
Text label associated with ContextMenu.
- Default element
- div
- Discovery hook
- data-sw-menu-label
- Role
- -
Data Attributes
Runtime hooks
Separator
Separates groups of ContextMenu items.
- Default element
- div
- Discovery hook
- data-sw-menu-separator
- Role
- separator
Data Attributes
Runtime hooks
Shortcut
Displays keyboard shortcut text for a ContextMenu item.
- Default element
- span
- Discovery hook
- data-sw-menu-shortcut
- Role
- -
Data Attributes
Runtime hooks
Submenu Root
Owns a nested submenu inside ContextMenu.
- Default element
- div
- Discovery hook
- data-sw-menu-submenu-root
- Role
- -
Props
closeDelay number 200
- Description
- Sets how long ContextMenu waits before closing.
- Kind
- option
- Targets
- root, submenuRoot
- Full type
- number
Data Attributes
Runtime hooks
State
Metadata
Submenu Trigger
Opens a nested submenu inside ContextMenu.
- Default element
- div
- Discovery hook
- data-sw-menu-submenu-trigger
- Role
- menuitem
Props
disabled boolean false
- Description
- Disables the Submenu Trigger part.
- Kind
- option
- Targets
- root, trigger, item, linkItem, checkboxItem, radioItem, submenuTrigger
- Full type
- boolean
Data Attributes
Runtime hooks
State
Metadata
Runtime API
- Factory
createContextMenu- Import
@starwind-ui/runtime/context-menu- Root hook
- root
data-sw-context-menu - Option props
- closeDelay, defaultOpen, disabled, modal, onCloseComplete, onOpenChange, open
Option Lifecycles
| Option | Lifecycle |
|---|---|
| closeDelay | constructor-only |
| defaultOpen | constructor-only |
| disabled | constructor-only |
| modal | constructor-only |
| onCloseComplete | constructor-only |
| onOpenChange | constructor-only |
| open | setter-backed |