# Context Menu

A menu of contextual actions opened from a pointer or keyboard target.

## Installation

Start from a Svelte 5 application, then install the component package, shared theme, and Bits UI peer:

```bash
pnpm add coss-svelte @coss-svelte/theme bits-ui
```

Import `@coss-svelte/theme/style-coss.css` after Tailwind from the application's global stylesheet.

## Usage

```svelte
<script lang="ts">
import {
	ContextMenu,
	ContextMenuItem,
	ContextMenuPopup,
	ContextMenuSeparator,
	ContextMenuTrigger,
} from "coss-svelte";
</script>

<ContextMenu>
	<ContextMenuTrigger class="block w-full max-w-sm" aria-label="Demo area">
		<div
			class="flex h-32 w-full items-center justify-center rounded-lg border border-dashed text-muted-foreground text-sm"
		>
			Right click here
		</div>
	</ContextMenuTrigger>
	<ContextMenuPopup>
		<ContextMenuItem>Back</ContextMenuItem>
		<ContextMenuItem>Forward</ContextMenuItem>
		<ContextMenuSeparator />
		<ContextMenuItem>Reload</ContextMenuItem>
	</ContextMenuPopup>
</ContextMenu>

```

## Anatomy

- `ContextMenu`
- `ContextMenuCheckboxItem`
- `ContextMenuGroup`
- `ContextMenuGroupLabel`
- `ContextMenuItem`
- `ContextMenuLinkItem`
- `ContextMenuPopup`
- `ContextMenuRadioGroup`
- `ContextMenuRadioItem`
- `ContextMenuSeparator`
- `ContextMenuShortcut`
- `ContextMenuSub`
- `ContextMenuSubPopup`
- `ContextMenuSubTrigger`
- `ContextMenuTrigger`

## API Reference

### ContextMenu

A menu of contextual actions opened from a pointer or keyboard target.

**Signatures**

- `{ open?: boolean; onOpenChange?: OnChangeFn<boolean>; onOpenChangeComplete?: OnChangeFn<boolean>; dir?: Direction }`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bind:open` | `boolean` | `false` | Open state for the popup or disclosure. Bind with `bind:open`. |
| `dir` | `Direction` | `"ltr"` | Sets logical keyboard navigation, placement, and chevron direction. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Bits UI ContextMenu.Root](https://bits-ui.com/docs/components/context-menu#root).

### ContextMenuCheckboxItem

Renders a bindable checkbox action with either a checkmark or switch presentation.

**Signatures**

- `{ checked?: boolean; onCheckedChange?: OnChangeFn<boolean>; indeterminate?: boolean; onIndeterminateChange?: OnChangeFn<boolean> }`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bind:checked` | `boolean` | `false` | Checked state for the control. Bind with `bind:checked` when supported. |
| `bind:indeterminate` | `boolean` | `false` | Displays the checkbox in an indeterminate state. |
| `variant` | `ContextMenuCheckboxVariant` | `"default"` | Visual variant for the component. |
| `disabled` | `boolean` | `false` | Disables interaction with the control. |
| `closeOnSelect` | `boolean` | `true` | Closes the context menu after the item is selected. |
| `textValue` | `string` | - | Provides plain text for keyboard typeahead when item content is complex. |

**Composition and refs**

- `children: Snippet<[MenuCheckboxItemSnippetProps]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI ContextMenu.CheckboxItem](https://bits-ui.com/docs/components/context-menu#checkbox-item).

### ContextMenuGroup

Groups related contextual actions without adding another interactive layer.

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI ContextMenu.Group](https://bits-ui.com/docs/components/context-menu#group).

### ContextMenuGroupLabel

Labels a related group of contextual actions.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset` | `boolean` | `false` | Adds leading space so the item aligns with rows that render an indicator. |

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI ContextMenu.GroupHeading](https://bits-ui.com/docs/components/context-menu#group-heading).

### ContextMenuItem

Renders a selectable contextual action with default or destructive styling.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `ContextMenuItemVariant` | `"default"` | Visual variant for the component. |
| `inset` | `boolean` | `false` | Adds leading space so the item aligns with rows that render an indicator. |
| `disabled` | `boolean` | `false` | Disables interaction with the control. |
| `closeOnSelect` | `boolean` | `true` | Closes the context menu after the item is selected. |
| `textValue` | `string` | - | Provides plain text for keyboard typeahead when item content is complex. |

**Composition and refs**

- `children: Snippet<[]>`
- `child: Snippet<[{ props: Record<string, unknown> }]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI ContextMenu.Item](https://bits-ui.com/docs/components/context-menu#item).

### ContextMenuLinkItem

Renders a menu item as a semantic anchor while preserving menu keyboard behavior.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | - | Renders the component as a link target when provided. |
| `target` | `HTMLAttributeAnchorTarget \| null` | - | Chooses the browsing context used by a link item. |
| `rel` | `string \| null` | - | Describes the relationship between a link item and its destination. |
| `download` | `string \| boolean` | - | Forwards the anchor download attribute to a link item. |
| `hreflang` | `string \| null` | - | Declares the language of a link item's destination. |
| `referrerpolicy` | `ReferrerPolicy \| null` | - | Controls referrer information sent when a link item is followed. |
| `variant` | `ContextMenuItemVariant` | `"default"` | Visual variant for the component. |
| `inset` | `boolean` | `false` | Adds leading space so the item aligns with rows that render an indicator. |
| `disabled` | `boolean` | `false` | Disables interaction with the control. |
| `closeOnSelect` | `boolean` | `true` | Closes the context menu after the item is selected. |
| `textValue` | `string` | - | Provides plain text for keyboard typeahead when item content is complex. |

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLAnchorElement \| null`

Inherits from [Bits UI ContextMenu.Item](https://bits-ui.com/docs/components/context-menu#item).

### ContextMenuPopup

Portals and positions the contextual menu surface at the pointer or keyboard anchor.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Side from which the surface appears. |
| `sideOffset` | `number` | `4` | Sets the distance between the pointer anchor and popup in pixels. |
| `align` | `"center" \| "start" \| "end"` | `"center"` | Aligns the popup with the virtual pointer anchor. |
| `alignOffset` | `number` | `0` | Offsets the popup from its preferred alignment in pixels. |
| `collisionPadding` | `number \| Partial<Record<"top" \| "right" \| "bottom" \| "left", number>>` | `8` | Keeps the popup inset from viewport collision boundaries. |
| `loop` | `boolean` | `true` | Wraps keyboard focus from the last menu item to the first and back. |
| `preventScroll` | `boolean` | `true` | Locks document scrolling while the root popup is open. |
| `forceMount` | `boolean` | - | Keeps content mounted while closed so transitions can complete. |
| `escapeKeydownBehavior` | `EscapeBehaviorType` | `"defer-otherwise-close"` | Defers to an open submenu Escape layer before closing the root menu. |
| `interactOutsideBehavior` | `InteractOutsideBehaviorType` | `"close"` | Controls how this floating layer responds to an outside pointer interaction. |
| `portalProps` | `{ disabled?: boolean; to?: PortalTarget }` | `{}` | Configures the exact Bits Portal target (`to`) or renders inline when `disabled`. |

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI ContextMenu.Content](https://bits-ui.com/docs/components/context-menu#content).

### ContextMenuRadioGroup

Coordinates one selected value across related radio menu items.

**Signatures**

- `{ value?: string; onValueChange?: OnChangeFn<string> }`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bind:value` | `string` | `""` | Selected radio item value. |

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI ContextMenu.RadioGroup](https://bits-ui.com/docs/components/context-menu#radio-group).

### ContextMenuRadioItem

Renders one bindable single-choice action within a radio group.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | - | Value selected by this radio item. |
| `disabled` | `boolean` | `false` | Disables interaction with the control. |
| `closeOnSelect` | `boolean` | `true` | Closes the context menu after the item is selected. |
| `textValue` | `string` | - | Provides plain text for keyboard typeahead when item content is complex. |

**Composition and refs**

- `children: Snippet<[MenuRadioItemSnippetProps]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI ContextMenu.RadioItem](https://bits-ui.com/docs/components/context-menu#radio-item).

### ContextMenuSeparator

Visually separates groups of contextual actions.

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI ContextMenu.Separator](https://bits-ui.com/docs/components/context-menu#separator).

### ContextMenuShortcut

Displays a semantic keyboard shortcut hint aligned to an item.

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Svelte <kbd> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### ContextMenuSub

Provides independent open state for a nested contextual menu.

**Signatures**

- `{ open?: boolean; onOpenChange?: OnChangeFn<boolean>; onOpenChangeComplete?: OnChangeFn<boolean> }`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bind:open` | `boolean` | `false` | Open state for the popup or disclosure. Bind with `bind:open`. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Bits UI ContextMenu.Sub](https://bits-ui.com/docs/components/context-menu#sub).

### ContextMenuSubPopup

Portals and positions the floating surface for a nested menu.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"right" in LTR; "left" in RTL` | Places the submenu at logical inline-end unless explicitly overridden. |
| `sideOffset` | `number` | `0` | Sets the distance between the pointer anchor and popup in pixels. |
| `align` | `"center" \| "start" \| "end"` | `"start"` | Aligns the submenu with its trigger. |
| `alignOffset` | `number` | `-5 (0 when align is center)` | Offsets non-centered submenu alignment toward its parent row. |
| `collisionPadding` | `number \| Partial<Record<"top" \| "right" \| "bottom" \| "left", number>>` | `8` | Keeps the submenu inset from viewport collision boundaries. |
| `loop` | `boolean` | `true` | Wraps keyboard focus from the last menu item to the first and back. |
| `forceMount` | `boolean` | - | Keeps content mounted while closed so transitions can complete. |
| `escapeKeydownBehavior` | `EscapeBehaviorType` | `"close"` | Closes this submenu before the root menu and restores focus to its trigger. |
| `interactOutsideBehavior` | `InteractOutsideBehaviorType` | `"defer-otherwise-close"` | Controls how this floating layer responds to an outside pointer interaction. |
| `portalProps` | `{ disabled?: boolean; to?: PortalTarget }` | `{}` | Configures the exact Bits Portal target (`to`) or renders inline when `disabled`. |

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI ContextMenu.SubContent](https://bits-ui.com/docs/components/context-menu#sub-content).

### ContextMenuSubTrigger

Opens a nested contextual menu with pointer or keyboard input.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset` | `boolean` | `false` | Adds leading space so the item aligns with rows that render an indicator. |
| `disabled` | `boolean` | `false` | Disables interaction with the control. |
| `textValue` | `string` | - | Provides plain text for keyboard typeahead when item content is complex. |
| `openDelay` | `number` | `100` | Delays pointer-triggered submenu opening by this many milliseconds. |

**Composition and refs**

- `children: Snippet<[]>`
- `child: Snippet<[{ props: Record<string, unknown> }]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI ContextMenu.SubTrigger](https://bits-ui.com/docs/components/context-menu#sub-trigger).

### ContextMenuTrigger

Defines the right-click target and opens from Shift+F10 or the Context Menu key.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Disables interaction with the control. |

**Composition and refs**

- `children: Snippet<[]>`
- `child: Snippet<[{ props: Record<string, unknown> }]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI ContextMenu.Trigger](https://bits-ui.com/docs/components/context-menu#trigger).

## Implementation Details

| Field | Value |
| --- | --- |
| Status | Stable |
| Foundation | bits |
| Category | Overlays & Popups |
| Particles | 8 |

## Status

Stable for the current coss-svelte surface.

## Agent Notes

- Import Svelte exports directly from `coss-svelte`.
- This is Svelte 5 code: use `class`, lowercase event properties, runes, snippets, and documented `bind:*` contracts. Do not emit JSX, React hooks, `className`, `asChild`, or Base UI imports.
- Prefer this route's example and generated API table over React COSS snippets; COSS React particles are design references only.
- The copy-and-own registry is a preview. Inspect `/r/context-menu.json` for the complete local file and dependency closure.
- Context Menu is stable in the current source catalog.