# Context Menu Primitive

Context Menu is a Starwind Runtime primitive in the composite-menu-overlay contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render ContextMenu anatomy with the Runtime wiring included.
```astro
---
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>
```

### React
Use the React primitive adapter when ContextMenu state participates in React rendering.
```tsx
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>
  );
}
```

### HTML
Render the ContextMenu data-sw-* contract yourself, then initialize createContextMenu.
```html
<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>
```

### Vue
Use the Vue 3.5 beta adapter to render ContextMenu anatomy.
```vue
<script setup lang="ts">
import ContextMenu from "@starwind-ui/vue/context-menu";
</script>

<template>
  <ContextMenu.Root>
    <ContextMenu.Trigger>Right click</ContextMenu.Trigger>
    <ContextMenu.Positioner>
      <ContextMenu.Popup>
        <ContextMenu.Item>Copy</ContextMenu.Item>
      </ContextMenu.Popup>
    </ContextMenu.Positioner>
  </ContextMenu.Root>
</template>
```
## 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 Context Menu Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-context-menu` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Context Menu is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | false | control | Sets whether Context Menu starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| modal | `boolean` | true | option | Makes Context Menu behave as a modal overlay. | - |
| closeDelay | `number` | 200 | option | Sets how long Context Menu waits before closing. | - |
| onCloseComplete | `(open: boolean, details: ContextMenuCloseCompleteDetails) => void` | - | callback | Runs after Context Menu has finished closing. | - |
| onOpenChange | `(open: boolean, details: ContextMenuOpenChangeDetails) => void` | - | callback | Runs when Context Menu opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-context-menu` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-sw-menu` | constant | - | Identifies Root metadata for styling and selectors. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-modal` | prop | - | Reflects the modal prop on the Root part. |
| `data-close-delay` | prop | - | Reflects the close delay prop on the Root part. |
| `data-state` | state | - | Reflects the current state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Context Menu is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| checked | `boolean` | checked | defaultChecked | `data-default-checked` | - | - | Tracks whether Context Menu is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| radioValue | `string` | value | defaultValue | `data-value` | - | - | Tracks the selected radio value for Context Menu. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | ContextMenuOpenChangeDetails | before-state-commit | Yes | Fires when Context Menu opens or closes. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
| closeComplete | onCloseComplete | starwind:close-complete | open: `boolean` | ContextMenuCloseCompleteDetails | after-state-commit | No | Fires after Context Menu has finished closing. | - |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | emit: false | Yes | Opens or closes Context Menu from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Context
| Name | Direction | Values |
| --- | --- | --- |
| context-menu-radio-group | provides | value, defaultValue, onValueChange |
| context-menu-radio-group | consumes | value |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-context-menu`, `data-sw-menu`, `data-default-open`, `data-disabled`, `data-modal`, `data-close-delay`, `data-state` | The context menu root needs both context-menu and Menu discovery attributes plus open, disabled, modal, close-delay, and initial state markers before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Trigger
The control that opens, closes, or targets the Context Menu content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-context-menu-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Trigger part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-context-menu-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-sw-menu-trigger` | constant | - | Identifies Trigger metadata for styling and selectors. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Trigger part. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-context-menu-trigger`, `data-sw-menu-trigger`, `aria-haspopup`, `aria-expanded`, `aria-disabled`, `data-disabled`, `data-state`, `tabindex` | Context menu triggers are focusable trigger regions that provide Menu trigger affordances before pointer, keyboard, and touch listeners attach. |

### Anchor
The virtual anchor used to position Context Menu content.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-context-menu-anchor` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-context-menu-anchor` | runtime | - | Marks the Anchor part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| anchor | No |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-context-menu-anchor`, `style` | The runtime creates a hidden document-positioned anchor at the pointer or keyboard-open position for the shared Menu floating runtime. |

### Portal
Moves Context Menu overlay content to the document body when needed.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-portal` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-portal` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |
| `data-container` | prop | - | Reflects the container prop on the Portal part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Portal part. |
| `data-sw-portal-placement` | constant | `runtime` | Identifies Portal metadata for styling and selectors. |
| `data-placement` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| portal | Yes |

### Positioner
Positions the Context Menu content relative to its trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-positioner` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Context Menu content. | - |
| align | `"start" \| "center" \| "end"` | "start" | option | Sets how Context Menu content aligns to its trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between Context Menu content and its trigger. | - |
| avoidCollisions | `boolean` | true | option | Allows Context Menu content to shift or flip to stay visible. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-positioner` | runtime | - | Marks the Positioner part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Positioner part. |
| `data-side` | prop | - | Reflects the side prop on the Positioner part. |
| `data-align` | prop | - | Reflects the align prop on the Positioner part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Positioner part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Positioner part. |
#### Refs
| Part | Public |
| --- | --- |
| positioner | Yes |

### Popup
The floating content container for Context Menu.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-popup` |
| Role | `menu` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Context Menu content. | - |
| align | `"start" \| "center" \| "end"` | "start" | option | Sets how Context Menu content aligns to its trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between Context Menu content and its trigger. | - |
| avoidCollisions | `boolean` | true | option | Allows Context Menu content to shift or flip to stay visible. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-popup` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
| `data-side` | prop | - | Reflects the side prop on the Popup part. |
| `data-align` | prop | - | Reflects the align prop on the Popup part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Popup part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-menu-popup`, `role`, `tabindex`, `data-state`, `data-side`, `data-align`, `data-side-offset`, `data-avoid-collisions`, `hidden` | The Menu-backed popup starts hidden and closed with menu semantics and placement hints before runtime positioning. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Item
An interactive item inside the Context Menu collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-item` |
| Role | `menuitem` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Item part. | - |
| closeOnClick | `boolean` | true | option | Closes Context Menu after the item is clicked. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-item` | runtime | - | Marks the Item part so Starwind Runtime can find it. |
| `data-close-on-click` | prop | - | Reflects the close on click prop on the Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Item part. |
#### Refs
| Part | Public |
| --- | --- |
| item | Yes |

### Link Item
A link-style item inside the Context Menu collection.
| Fact | Value |
| --- | --- |
| Default element | `a` |
| Discovery hook | `data-sw-menu-link-item` |
| Role | `menuitem` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Link Item part. | - |
| closeOnClick | `boolean` | false | option | Closes Context Menu after the item is clicked. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-link-item` | runtime | - | Marks the Link Item part so Starwind Runtime can find it. |
| `data-close-on-click` | prop | - | Reflects the close on click prop on the Link Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Link Item part. |
#### Refs
| Part | Public |
| --- | --- |
| linkItem | Yes |

### Checkbox Item
A checkbox-style item inside the Context Menu collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-checkbox-item` |
| Role | `menuitemcheckbox` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Checkbox Item part. | - |
| checked | `boolean` | - | control | Controls whether Context Menu is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| defaultChecked | `boolean` | false | control | Sets whether Context Menu starts checked for uncontrolled usage. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| closeOnClick | `boolean` | false | option | Closes Context Menu after the item is clicked. | - |
| onCheckedChange | `(checked: boolean, details: MenuCheckedChangeDetails) => void` | - | callback | Runs when the Context Menu checked state changes. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-checkbox-item` | runtime | - | Marks the Checkbox Item part so Starwind Runtime can find it. |
| `data-default-checked` | state | - | Reflects the default checked state on the Checkbox Item part. |
| `data-close-on-click` | prop | - | Reflects the close on click prop on the Checkbox Item part. |
| `data-checked` | state | - | Reflects the checked state on the Checkbox Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Checkbox Item part. |
| `data-unchecked` | state | - | Reflects the unchecked state on the Checkbox Item part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checked | `boolean` | checked | defaultChecked | `data-default-checked` | - | - | Tracks whether Context Menu is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checkedChange | onCheckedChange | starwind:checked-change | checked: `boolean` | MenuCheckedChangeDetails | before-state-commit | Yes | Fires when the checked state changes for Context Menu. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Refs
| Part | Public |
| --- | --- |
| checkboxItem | Yes |

### Checkbox Item Indicator
Shows the checked state for a Context Menu checkbox item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-menu-checkbox-item-indicator` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-checkbox-item-indicator` | runtime | - | Marks the Checkbox Item Indicator part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Checkbox Item Indicator part. |
#### Refs
| Part | Public |
| --- | --- |
| checkboxItemIndicator | Yes |

### Radio Group
Groups related radio items inside Context Menu.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-radio-group` |
| Role | `group` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `string` | - | control | Controls the current Context Menu value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
| defaultValue | `string` | - | control | Sets the initial Context Menu value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
| onValueChange | `(value: string, details: MenuValueChangeDetails) => void` | - | callback | Runs when the Context Menu value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-radio-group` | runtime | - | Marks the Radio Group part so Starwind Runtime can find it. |
| `data-value` | state | - | Reflects the value state on the Radio Group part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| radioValue | `string` | value | defaultValue | `data-value` | - | - | Tracks the selected radio value for Context Menu. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `string` | MenuValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Context Menu. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Refs
| Part | Public |
| --- | --- |
| radioGroup | Yes |

### Radio Item
A radio-style item inside the Context Menu collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-radio-item` |
| Role | `menuitemradio` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Radio Item part. | - |
| checked | `boolean` | - | control | Controls whether Context Menu is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| defaultChecked | `boolean` | false | control | Sets whether Context Menu starts checked for uncontrolled usage. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| closeOnClick | `boolean` | false | option | Closes Context Menu after the item is clicked. | - |
| value | `string` | - | option | Controls the current Context Menu value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-radio-item` | runtime | - | Marks the Radio Item part so Starwind Runtime can find it. |
| `data-value` | prop | - | Reflects the value prop on the Radio Item part. |
| `data-default-checked` | state | - | Reflects the default checked state on the Radio Item part. |
| `data-close-on-click` | prop | - | Reflects the close on click prop on the Radio Item part. |
| `data-checked` | state | - | Reflects the checked state on the Radio Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Radio Item part. |
| `data-unchecked` | state | - | Reflects the unchecked state on the Radio Item part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checked | `boolean` | checked | defaultChecked | `data-default-checked` | - | - | Tracks whether Context Menu is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state and listen for starwind:checked-change.<br>**Runtime / HTML:** Use data-default-checked for initial state and listen for starwind:checked-change. |
| radioValue | `string` | value | defaultValue | `data-value` | - | - | Tracks the selected radio value for Context Menu. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state and listen for starwind:value-change.<br>**Runtime / HTML:** Use data-value for initial state and listen for starwind:value-change. |
#### Refs
| Part | Public |
| --- | --- |
| radioItem | Yes |

### Radio Item Indicator
Shows the selected state for a Context Menu radio item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-menu-radio-item-indicator` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-radio-item-indicator` | runtime | - | Marks the Radio Item Indicator part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Radio Item Indicator part. |
#### Refs
| Part | Public |
| --- | --- |
| radioItemIndicator | Yes |

### Group
Groups related Context Menu items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-group` |
| Role | `group` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-group` | runtime | - | Marks the Group part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| group | Yes |

### Label
Text label associated with Context Menu.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-label` | runtime | - | Marks the Label part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| label | Yes |

### Separator
Separates groups of Context Menu items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-separator` |
| Role | `separator` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-separator` | runtime | - | Marks the Separator part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| separator | Yes |

### Shortcut
Displays keyboard shortcut text for a Context Menu item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-menu-shortcut` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-shortcut` | runtime | - | Marks the Shortcut part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| shortcut | Yes |

### Submenu Root
Owns a nested submenu inside Context Menu.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-submenu-root` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| closeDelay | `number` | 200 | option | Sets how long Context Menu waits before closing. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-submenu-root` | runtime | - | Marks the Submenu Root part so Starwind Runtime can find it. |
| `data-close-delay` | prop | - | Reflects the close delay prop on the Submenu Root part. |
| `data-state` | state | - | Reflects the current state on the Submenu Root part. |
#### Refs
| Part | Public |
| --- | --- |
| submenuRoot | Yes |

### Submenu Trigger
Opens a nested submenu inside Context Menu.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-menu-submenu-trigger` |
| Role | `menuitem` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| disabled | `boolean` | false | option | Disables the Submenu Trigger part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-menu-submenu-trigger` | runtime | - | Marks the Submenu Trigger part so Starwind Runtime can find it. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Submenu Trigger part. |
| `data-state` | state | - | Reflects the current state on the Submenu Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| submenuTrigger | Yes |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createContextMenu`](/docs/runtime/#create-context-menu) |
| Import | `@starwind-ui/runtime/context-menu` |
| Root part | root |
| Option props | closeDelay, defaultOpen, disabled, modal, onCloseComplete, onOpenChange, open |
| Option lifecycles | closeDelay: constructor-only, defaultOpen: constructor-only, disabled: constructor-only, modal: constructor-only, onCloseComplete: constructor-only, onOpenChange: constructor-only, open: setter-backed |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Context Menu](/docs/components/context-menu/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/context-menu` | `createContextMenu` |
| Astro Primitive | `@starwind-ui/astro/context-menu` | `ContextMenu`, `ContextMenuRoot`, `ContextMenuTrigger`, `ContextMenuPortal`, `ContextMenuPositioner`, `ContextMenuPopup`, `ContextMenuItem`, `ContextMenuLinkItem`, `ContextMenuCheckboxItem`, `ContextMenuCheckboxItemIndicator`, `ContextMenuRadioGroup`, `ContextMenuRadioItem`, `ContextMenuRadioItemIndicator`, `ContextMenuGroup`, `ContextMenuLabel`, `ContextMenuSeparator`, `ContextMenuShortcut`, `ContextMenuSubmenuRoot`, `ContextMenuSubmenuTrigger` |
| React Primitive | `@starwind-ui/react/context-menu` | `ContextMenu`, `ContextMenuRoot`, `ContextMenuTrigger`, `ContextMenuPortal`, `ContextMenuPositioner`, `ContextMenuPopup`, `ContextMenuItem`, `ContextMenuLinkItem`, `ContextMenuCheckboxItem`, `ContextMenuCheckboxItemIndicator`, `ContextMenuRadioGroup`, `ContextMenuRadioItem`, `ContextMenuRadioItemIndicator`, `ContextMenuGroup`, `ContextMenuLabel`, `ContextMenuSeparator`, `ContextMenuShortcut`, `ContextMenuSubmenuRoot`, `ContextMenuSubmenuTrigger` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `ContextMenu` |
| runtime-factory | `createContextMenu` |
| part | `ContextMenu.Root` |
| part | `ContextMenu.Trigger` |
| part | `ContextMenu.Portal` |
| part | `ContextMenu.Positioner` |
| part | `ContextMenu.Popup` |
| part | `ContextMenu.Item` |
| part | `ContextMenu.LinkItem` |
| part | `ContextMenu.CheckboxItem` |
| part | `ContextMenu.CheckboxItemIndicator` |
| part | `ContextMenu.RadioGroup` |
| part | `ContextMenu.RadioItem` |
| part | `ContextMenu.RadioItemIndicator` |
| part | `ContextMenu.Group` |
| part | `ContextMenu.Label` |
| part | `ContextMenu.Separator` |
| part | `ContextMenu.Shortcut` |
| part | `ContextMenu.SubmenuRoot` |
| part | `ContextMenu.SubmenuTrigger` |
## Changelog
### v1.1.1
- Connected owned group headings to their groups with aria-labelledby so assistive technology can identify each group.
### v1.1.0
- Added portable Portal container and disabled controls, with deterministic framework and Runtime placement reporting for nested floating content.
- Kept touch-opened parent menus active while focus moves into a submenu so mobile submenus remain anchored to their triggers.
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.2
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.1
- Enabled modal background-scroll locking by default while the menu is open.
### v0.1.0
- Introduced pointer-triggered menus with keyboard navigation, submenus, checked items, and floating placement.