Skip to main content

Starwind UI v3.0 beta is now available! Read the migration guide

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>

Floating Behavior

FactValue
Anchor partanchor
Positioner partpositioner
Popup partpopup
Portal partportal
Option propsside, 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

Prop Type Default Toggle
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

Event Callback Value Toggle
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

State Type Props Toggle
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
Attribute Value Description
data-sw-context-menu - Marks the Root part so Starwind Runtime can find it.
State
Attribute Value Description
data-state - Reflects the current state on the Root part.
Metadata
Attribute Value Description
data-sw-menu - Identifies Root metadata for styling and selectors.
data-default-open - Reflects the default open prop on the Root part.
data-disabled - Reflects the disabled prop on the Root part.
data-modal - Reflects the modal prop on the Root part.
data-close-delay - Reflects the close delay prop on the Root part.

Trigger

The control that opens, closes, or targets the ContextMenu content.

Default element
div
Discovery hook
data-sw-context-menu-trigger
Role
-

Props

Prop Type Default Toggle
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
Attribute Value Description
data-sw-context-menu-trigger - Marks the Trigger part so Starwind Runtime can find it.
State
Attribute Value Description
data-state - Reflects the current state on the Trigger part.
Metadata
Attribute Value Description
data-sw-menu-trigger - Identifies Trigger metadata for styling and selectors.
data-disabled - Reflects the disabled prop on the Trigger part.

Anchor

The virtual anchor used to position ContextMenu content.

Default element
span
Discovery hook
data-sw-context-menu-anchor
Role
-

Data Attributes

Runtime hooks
Attribute Value Description
data-sw-context-menu-anchor - Marks the Anchor part so Starwind Runtime can find it.

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
Attribute Value Description
data-sw-menu-portal - Marks the Portal part so Starwind Runtime can find it.

Positioner

Positions the ContextMenu content relative to its trigger.

Default element
div
Discovery hook
data-sw-menu-positioner
Role
-

Props

Prop Type Default Toggle
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
Attribute Value Description
data-sw-menu-positioner - Marks the Positioner part so Starwind Runtime can find it.
State
Attribute Value Description
data-state - Reflects the current state on the Positioner part.
Metadata
Attribute Value Description
data-side - Reflects the side prop on the Positioner part.
data-align - Reflects the align prop on the Positioner part.
data-side-offset - Reflects the side offset prop on the Positioner part.
data-avoid-collisions - Reflects the avoid collisions prop on the Positioner part.

The floating content container for ContextMenu.

Default element
div
Discovery hook
data-sw-menu-popup
Role
menu

Props

Prop Type Default Toggle
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
Attribute Value Description
data-sw-menu-popup - Marks the Popup part so Starwind Runtime can find it.
State
Attribute Value Description
data-state - Reflects the current state on the Popup part.
Metadata
Attribute Value Description
data-side - Reflects the side prop on the Popup part.
data-align - Reflects the align prop on the Popup part.
data-side-offset - Reflects the side offset prop on the Popup part.
data-avoid-collisions - Reflects the avoid collisions prop on the Popup part.

Item

An interactive item inside the ContextMenu collection.

Default element
div
Discovery hook
data-sw-menu-item
Role
menuitem

Props

Prop Type Default Toggle
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
Attribute Value Description
data-sw-menu-item - Marks the Item part so Starwind Runtime can find it.
Metadata
Attribute Value Description
data-close-on-click - Reflects the close on click prop on the Item part.
data-disabled - Reflects the disabled prop on the Item part.

A link-style item inside the ContextMenu collection.

Default element
a
Discovery hook
data-sw-menu-link-item
Role
menuitem

Props

Prop Type Default Toggle
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
Attribute Value Description
data-sw-menu-link-item - Marks the Link Item part so Starwind Runtime can find it.
Metadata
Attribute Value Description
data-close-on-click - Reflects the close on click prop on the Link Item part.
data-disabled - Reflects the disabled prop on the Link Item part.

Checkbox Item

A checkbox-style item inside the ContextMenu collection.

Default element
div
Discovery hook
data-sw-menu-checkbox-item
Role
menuitemcheckbox

Props

Prop Type Default Toggle
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

Event Callback Value Toggle
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

State Type Props Toggle
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
Attribute Value Description
data-sw-menu-checkbox-item - Marks the Checkbox Item part so Starwind Runtime can find it.
State
Attribute Value Description
data-default-checked - Reflects the default checked state on the Checkbox Item part.
data-checked - Reflects the checked state on the Checkbox Item part.
data-unchecked - Reflects the unchecked state on the Checkbox Item part.
Metadata
Attribute Value Description
data-close-on-click - Reflects the close on click prop on the Checkbox Item part.
data-disabled - Reflects the disabled prop on the Checkbox Item part.

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
Attribute Value Description
data-sw-menu-checkbox-item-indicator - Marks the Checkbox Item Indicator part so Starwind Runtime can find it.
State
Attribute Value Description
data-state - Reflects the current state on the Checkbox Item Indicator part.

Radio Group

Groups related radio items inside ContextMenu.

Default element
div
Discovery hook
data-sw-menu-radio-group
Role
group

Props

Prop Type Default Toggle
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

Event Callback Value Toggle
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

State Type Props Toggle
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
Attribute Value Description
data-sw-menu-radio-group - Marks the Radio Group part so Starwind Runtime can find it.
State
Attribute Value Description
data-value - Reflects the value state on the Radio Group part.

Radio Item

A radio-style item inside the ContextMenu collection.

Default element
div
Discovery hook
data-sw-menu-radio-item
Role
menuitemradio

Props

Prop Type Default Toggle
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

State Type Props Toggle
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
Attribute Value Description
data-sw-menu-radio-item - Marks the Radio Item part so Starwind Runtime can find it.
State
Attribute Value Description
data-default-checked - Reflects the default checked state on the Radio Item part.
data-checked - Reflects the checked state on the Radio Item part.
data-unchecked - Reflects the unchecked state on the Radio Item part.
Metadata
Attribute Value Description
data-value - Reflects the value prop on the Radio Item part.
data-close-on-click - Reflects the close on click prop on the Radio Item part.
data-disabled - Reflects the disabled prop on the Radio Item part.

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
Attribute Value Description
data-sw-menu-radio-item-indicator - Marks the Radio Item Indicator part so Starwind Runtime can find it.
State
Attribute Value Description
data-state - Reflects the current state on the Radio Item Indicator part.

Group

Groups related ContextMenu items.

Default element
div
Discovery hook
data-sw-menu-group
Role
group

Data Attributes

Runtime hooks
Attribute Value Description
data-sw-menu-group - Marks the Group part so Starwind Runtime can find it.

Label

Text label associated with ContextMenu.

Default element
div
Discovery hook
data-sw-menu-label
Role
-

Data Attributes

Runtime hooks
Attribute Value Description
data-sw-menu-label - Marks the Label part so Starwind Runtime can find it.

Separator

Separates groups of ContextMenu items.

Default element
div
Discovery hook
data-sw-menu-separator
Role
separator

Data Attributes

Runtime hooks
Attribute Value Description
data-sw-menu-separator - Marks the Separator part so Starwind Runtime can find it.

Shortcut

Displays keyboard shortcut text for a ContextMenu item.

Default element
span
Discovery hook
data-sw-menu-shortcut
Role
-

Data Attributes

Runtime hooks
Attribute Value Description
data-sw-menu-shortcut - Marks the Shortcut part so Starwind Runtime can find it.

Owns a nested submenu inside ContextMenu.

Default element
div
Discovery hook
data-sw-menu-submenu-root
Role
-

Props

Prop Type Default Toggle
closeDelay number 200
Description
Sets how long ContextMenu waits before closing.
Kind
option
Targets
root, submenuRoot
Full type
number

Data Attributes

Runtime hooks
Attribute Value Description
data-sw-menu-submenu-root - Marks the Submenu Root part so Starwind Runtime can find it.
State
Attribute Value Description
data-state - Reflects the current state on the Submenu Root part.
Metadata
Attribute Value Description
data-close-delay - Reflects the close delay prop on the Submenu Root part.

Opens a nested submenu inside ContextMenu.

Default element
div
Discovery hook
data-sw-menu-submenu-trigger
Role
menuitem

Props

Prop Type Default Toggle
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
Attribute Value Description
data-sw-menu-submenu-trigger - Marks the Submenu Trigger part so Starwind Runtime can find it.
State
Attribute Value Description
data-state - Reflects the current state on the Submenu Trigger part.
Metadata
Attribute Value Description
data-disabled - Reflects the disabled prop on the Submenu Trigger part.

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

OptionLifecycle
closeDelayconstructor-only
defaultOpenconstructor-only
disabledconstructor-only
modalconstructor-only
onCloseCompleteconstructor-only
onOpenChangeconstructor-only
opensetter-backed

Runtime Setters

Method Target Description
setOpen state: open Opens or closes ContextMenu from Runtime code.
Component Relationship
Context Menu Direct primitive