# Context Menu

```astro
---
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 variant="destructive">Delete</ContextMenuItem>
          </ContextMenuGroup>
        </ContextMenuSubContent>
      </ContextMenuSub>
    </ContextMenuGroup>
    <ContextMenuSeparator />
    <ContextMenuGroup>
      <ContextMenuCheckboxItem checked>Show Bookmarks</ContextMenuCheckboxItem>
      <ContextMenuCheckboxItem>Show Full URLs</ContextMenuCheckboxItem>
    </ContextMenuGroup>
  </ContextMenuContent>
</ContextMenu>
```

## Installation

```bash
npx starwind@latest add context-menu
```

## Usage

### Basic

A simple context menu with a few actions.

```astro
---
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  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>
    <ContextMenuGroup>
      <ContextMenuItem>Back</ContextMenuItem>
      <ContextMenuItem disabled>Forward</ContextMenuItem>
      <ContextMenuItem>Reload</ContextMenuItem>
    </ContextMenuGroup>
  </ContextMenuContent>
</ContextMenu>
```

### Submenu

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

```astro
---
import {
  ContextMenu,
  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>
        Copy
        <ContextMenuShortcut>⌘C</ContextMenuShortcut>
      </ContextMenuItem>
      <ContextMenuItem>
        Cut
        <ContextMenuShortcut>⌘X</ContextMenuShortcut>
      </ContextMenuItem>
    </ContextMenuGroup>
    <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 variant="destructive">Delete</ContextMenuItem>
        </ContextMenuGroup>
      </ContextMenuSubContent>
    </ContextMenuSub>
  </ContextMenuContent>
</ContextMenu>
```

### Shortcuts

Add `ContextMenuShortcut` to show keyboard hints.

```astro
---
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  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>
    <ContextMenuGroup>
      <ContextMenuItem>
        Back
        <ContextMenuShortcut>⌘[</ContextMenuShortcut>
      </ContextMenuItem>
      <ContextMenuItem disabled>
        Forward
        <ContextMenuShortcut>⌘]</ContextMenuShortcut>
      </ContextMenuItem>
      <ContextMenuItem>
        Reload
        <ContextMenuShortcut>⌘R</ContextMenuShortcut>
      </ContextMenuItem>
    </ContextMenuGroup>
    <ContextMenuSeparator />
    <ContextMenuGroup>
      <ContextMenuItem>
        Save
        <ContextMenuShortcut>⌘S</ContextMenuShortcut>
      </ContextMenuItem>
      <ContextMenuItem>
        Save As...
        <ContextMenuShortcut>⇧⌘S</ContextMenuShortcut>
      </ContextMenuItem>
    </ContextMenuGroup>
  </ContextMenuContent>
</ContextMenu>
```

### With Icons

Combine icons with labels for quick scanning.

```astro
---
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuTrigger,
} from "@/components/starwind/context-menu";
import Copy from "@tabler/icons/outline/copy.svg";
import Edit from "@tabler/icons/outline/edit.svg";
import Trash from "@tabler/icons/outline/trash.svg";
---

<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>
    <ContextMenuGroup>
      <ContextMenuItem>
        <Copy />
        Copy
      </ContextMenuItem>
      <ContextMenuItem>
        <Edit />
        Rename
      </ContextMenuItem>
    </ContextMenuGroup>
    <ContextMenuSeparator />
    <ContextMenuGroup>
      <ContextMenuItem variant="destructive">
        <Trash />
        Delete
      </ContextMenuItem>
    </ContextMenuGroup>
  </ContextMenuContent>
</ContextMenu>
```

### Checkboxes

Use `ContextMenuCheckboxItem` for toggle actions.

```astro
---
import {
  ContextMenu,
  ContextMenuCheckboxItem,
  ContextMenuContent,
  ContextMenuGroup,
  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>
    <ContextMenuGroup>
      <ContextMenuCheckboxItem checked>Show Bookmarks Bar</ContextMenuCheckboxItem>
      <ContextMenuCheckboxItem>Show Full URLs</ContextMenuCheckboxItem>
      <ContextMenuCheckboxItem checked>Show Developer Tools</ContextMenuCheckboxItem>
    </ContextMenuGroup>
  </ContextMenuContent>
</ContextMenu>
```

## Composition

Use the following composition to build a `ContextMenu`:

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

## API Reference

### ContextMenu

The root component that serves as a container for all context-menu related components. It uses the Dropdown engine in `context-menu` mode.

| Prop | Type | Default |
|------|------|---------|
| `closeDelay` | `number` | `200` |
| `class` | `string` | - |

```astro
<ContextMenu>
  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuItem>Action</ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>
```

**Additional Notes:**
- `closeDelay`: Time in milliseconds to wait before closing related hover interactions for nested content
- Right-click (or touch long-press) behavior is built in and not configurable through a `menuMode` prop

### ContextMenuTrigger

The area users right-click (or long-press on touch devices) to open the context menu.

| Prop | Type | Default |
|------|------|---------|
| `class` | `string` | - |

```astro
<ContextMenuTrigger class="rounded-md border border-dashed p-6 text-sm">
  Right click here
</ContextMenuTrigger>
```

**Additional Notes:**
- Accepts all native `HTMLAttributes<"div">` props
- Includes built-in accessibility attributes (`tabindex="0"`, `aria-haspopup="menu"`, `aria-expanded="false"`)

### ContextMenuContent

The container for context menu content. This component renders the menu with animation effects.

| Prop | Type | Default |
|------|------|---------|
| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` |
| `align` | `"start" \| "center" \| "end"` | `"start"` |
| `sideOffset` | `number` | `4` |
| `animationDuration` | `number` | `150` |
| `class` | `string` | - |

```astro
<ContextMenuContent align="center" sideOffset={8}>
  <ContextMenuItem>Open</ContextMenuItem>
</ContextMenuContent>
```

**Additional Notes:**
- `side`: Side of the menu relative to the trigger (`"top"`, `"bottom"`, `"left"`, or `"right"`)
- `align`: Alignment of the menu relative to the trigger
- `sideOffset`: Offset distance in pixels from the trigger
- `animationDuration`: Open and close animation duration in milliseconds

### ContextMenuItem

A component for creating interactive items within the context menu.

| Prop | Type | Default |
|------|------|---------|
| `as` | `HTMLTag` | `"div"` |
| `inset` | `boolean` | `false` |
| `disabled` | `boolean` | `false` |
| `class` | `string` | - |

```astro
<ContextMenuItem as="a" href="#">Open link</ContextMenuItem>
```

**Additional Notes:**
- `as`: HTML element to render the item as (for example, `"a"` or `"button"`)
- `inset`: Whether the item has left padding for alignment with items that have icons

### ContextMenuLabel

A component for rendering a non-interactive label within the context menu.

| Prop | Type | Default |
|------|------|---------|
| `inset` | `boolean` | `false` |
| `class` | `string` | - |

```astro
<ContextMenuLabel>Section Title</ContextMenuLabel>
```

**Additional Notes:**
- `inset`: Whether the label has left padding for alignment with items that have icons

### ContextMenuSeparator

A component for creating a visual separator between context menu items.

| Prop | Type | Default |
|------|------|---------|
| `class` | `string` | - |

```astro
<ContextMenuSeparator />
```

### ContextMenuCheckboxItem

A component for creating checkbox items within the context menu. It includes a built-in check indicator and emits a custom event when toggled.

| Prop | Type | Default |
|------|------|---------|
| `checked` | `boolean` | `false` |
| `closeOnClick` | `boolean` | `false` |
| `inset` | `boolean` | `false` |
| `disabled` | `boolean` | `false` |
| `class` | `string` | - |

```astro
<ContextMenuCheckboxItem checked>
  Show status bar
</ContextMenuCheckboxItem>
```

**Additional Notes:**
- `checked`: Controls the initial checked state of the item
- `closeOnClick`: Whether the menu should close when the checkbox item is clicked
- `inset`: Whether the item has left padding for alignment with items that have icons
- `disabled`: Prevents interaction and keyboard focus
- Emits a `starwind-dropdown-checkbox:change` custom event with `{ checked: boolean }` detail when toggled

### ContextMenuGroup

A wrapper component for grouping related context menu items together. It applies the `role="group"` attribute for accessibility.

| Prop | Type | Default |
|------|------|---------|
| `class` | `string` | - |

```astro
<ContextMenuGroup>
  <ContextMenuLabel>Team</ContextMenuLabel>
  <ContextMenuItem>Invite users</ContextMenuItem>
  <ContextMenuItem>New Team</ContextMenuItem>
</ContextMenuGroup>
```

### ContextMenuShortcut

An optional helper for rendering keyboard hints aligned to the end of a context menu item.

| Prop | Type | Default |
|------|------|---------|
| `class` | `string` | - |

```astro
<ContextMenuItem>
  Profile
  <ContextMenuShortcut>Shift+Ctrl+P</ContextMenuShortcut>
</ContextMenuItem>
```

### ContextMenuSub

A wrapper for submenu trigger and content pairs inside a context menu.

| Prop | Type | Default |
|------|------|---------|
| `class` | `string` | - |

```astro
<ContextMenuSub>
  <ContextMenuSubTrigger>Invite users</ContextMenuSubTrigger>
  <ContextMenuSubContent>
    <ContextMenuItem>Email</ContextMenuItem>
  </ContextMenuSubContent>
</ContextMenuSub>
```

### ContextMenuSubTrigger

The interactive trigger that opens a nested submenu.

| Prop | Type | Default |
|------|------|---------|
| `inset` | `boolean` | `false` |
| `disabled` | `boolean` | `false` |
| `class` | `string` | - |

```astro
<ContextMenuSubTrigger inset>Invite users</ContextMenuSubTrigger>
```

**Additional Notes:**
- `inset`: Adds left padding to align with items that include icons
- `disabled`: Prevents interaction and keyboard focus

### ContextMenuSubContent

The content panel rendered when a submenu trigger is opened.

| Prop | Type | Default |
|------|------|---------|
| `animationDuration` | `number` | `150` |
| `sideOffset` | `number` | `0` |
| `class` | `string` | - |

```astro
<ContextMenuSubContent animationDuration={200}>
  <ContextMenuItem>Email</ContextMenuItem>
  <ContextMenuItem>Message</ContextMenuItem>
</ContextMenuSubContent>
```

**Additional Notes:**
- `animationDuration`: Open and close animation duration in milliseconds
- `sideOffset`: Offset distance in pixels from the submenu trigger