---
title: "ContextMenu"
description: "Opens a menu at the pointer or from the keyboard Menu key."
category: "Overlays"
slug: context-menu
url: /components/context-menu
since: "0.2.0"
status: "stable"
---

# ContextMenu

Opens a menu at the pointer or from the keyboard Menu key.

## Import

```svelte
import { ContextMenu } from '@elluzion/iv-ui';
```

## Preview

Right-click the panel, or focus it and press Shift+F10.

```svelte
<script lang="ts">
	import type { MenuEntry } from '@elluzion/iv-ui';
	import { ContextMenu } from '@elluzion/iv-ui';

	let last = $state('none');

	const entries: MenuEntry[] = [
		{ type: 'header', id: 'file', label: 'File' },
		{ type: 'item', id: 'open', item: { label: 'Open', shortcut: '⏎' } },
		{ type: 'item', id: 'rename', item: { label: 'Rename', shortcut: 'F2' } },
		{ type: 'separator', id: 'sep' },
		{ type: 'item', id: 'delete', item: { label: 'Delete', shortcut: '⌫' } }
	];

	function handle(_event: MouseEvent, entry: MenuEntry) {
		last = entry.type === 'item' ? entry.item.label : entry.type;
	}
</script>

<div class="stack">
	<ContextMenu {entries} label="File actions" onclick={handle}>
		<div class="area">
			<strong>Right-click this panel</strong>
			<span>or focus it and press Shift+F10</span>
		</div>
	</ContextMenu>
	<p class="readout">last action: {last}</p>
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		align-items: center;
		gap: var(--iv_spacing-sm);
		width: 100%;
	}

	.area {
		display: flex;
		flex-direction: column;
		align-items: center;
		gap: var(--iv_spacing-2xs);
		width: 100%;
		max-width: 360px;
		padding: var(--iv_spacing-2xl);
		border: 1px dashed var(--iv_border);
		border-radius: var(--iv_radius-sm);
		background: var(--iv_surface-raised);
		color: var(--iv_foreground-dim);
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
	}

	.area strong {
		color: var(--iv_foreground);
		font-weight: 500;
	}

	.readout {
		margin: 0;
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_foreground-dim);
	}
</style>
```

## Usage

- Wrap the area that owns the menu; `entries` uses the same shape as `Menu`.
- Right-click opens on pointer devices; `touchTrigger` picks the touch gesture.
- Shift+F10 or the Menu key opens it from the keyboard, anchored to the trigger.

## Examples

### Submenu

A submenu opens on hover or with the right arrow key.

```svelte
<script lang="ts">
	import type { MenuEntry } from '@elluzion/iv-ui';
	import { ContextMenu } from '@elluzion/iv-ui';

	let last = $state('none');

	const entries: MenuEntry[] = [
		{ type: 'item', id: 'copy', item: { label: 'Copy id', shortcut: '⌘C' } },
		{
			type: 'submenu',
			id: 'export',
			label: 'Export as',
			children: [
				{ type: 'item', id: 'json', item: { label: 'JSON' } },
				{ type: 'item', id: 'csv', item: { label: 'CSV' } },
				{ type: 'item', id: 'yaml', item: { label: 'YAML', disabled: true } }
			]
		},
		{ type: 'item', id: 'archive', item: { label: 'Archive' } }
	];

	function handle(_event: MouseEvent, entry: MenuEntry) {
		if (entry.type === 'item') last = entry.item.label;
	}
</script>

<div class="stack">
	<ContextMenu {entries} label="Record actions" onclick={handle}>
		<div class="area">Right-click for the record actions</div>
	</ContextMenu>
	<p class="readout">last action: {last}</p>
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		align-items: center;
		gap: var(--iv_spacing-sm);
		width: 100%;
	}

	.area {
		width: 100%;
		max-width: 360px;
		padding: var(--iv_spacing-2xl);
		border: 1px dashed var(--iv_border);
		border-radius: var(--iv_radius-sm);
		background: var(--iv_surface-raised);
		color: var(--iv_foreground-dim);
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		text-align: center;
	}

	.readout {
		margin: 0;
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_foreground-dim);
	}
</style>
```

### Touch trigger

`touchTrigger="click"` opens the menu with a tap.

```svelte
<script lang="ts">
	import type { MenuEntry } from '@elluzion/iv-ui';
	import { ContextMenu } from '@elluzion/iv-ui';

	let last = $state('none');

	const entries: MenuEntry[] = [
		{ type: 'item', id: 'pin', item: { label: 'Pin to top' } },
		{ type: 'item', id: 'mute', item: { label: 'Mute alerts' } },
		{ type: 'item', id: 'leave', item: { label: 'Leave workspace' } }
	];

	function handle(_event: MouseEvent, entry: MenuEntry) {
		if (entry.type === 'item') last = entry.item.label;
	}
</script>

<div class="stack">
	<ContextMenu {entries} label="Workspace actions" touchTrigger="click" onclick={handle}>
		<button type="button" class="area">Tap for workspace actions</button>
	</ContextMenu>
	<p class="readout">last action: {last}</p>
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		align-items: center;
		gap: var(--iv_spacing-sm);
		width: 100%;
	}

	.area {
		padding: var(--iv_spacing-md) var(--iv_spacing-lg);
		border: 1px solid var(--iv_border);
		border-radius: var(--iv_radius-sm);
		background: var(--iv_surface-raised);
		color: var(--iv_foreground);
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		cursor: pointer;
	}

	.readout {
		margin: 0;
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_foreground-dim);
	}
</style>
```

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `entries` **required** | `MenuEntry[]` | — | Menu structure: headers, items, separators, and submenus. |
| `label` | `string` | `''` | Accessible name for the menu. |
| `id` | `string` | `''` | Element id. A generated id is used when omitted. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |
| `touchTrigger` | `'longpress' \| 'dblclick' \| 'click'` | `'longpress'` | Gesture that opens the menu on touch devices. |

### Events

| Event | Handler type | Description |
| --- | --- | --- |
| `click` | `(e: MouseEvent, entry: MenuEntry) => void` | Called with the native event and the activated entry. |
| `open` | `() => void` | Called after the layer opens. |
| `close` | `() => void` | Called when the layer requests to close. |

The legacy `on:name` form is accepted for every event.

### Snippets

| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | The area that owns the context menu. |

### Tokens used

`--iv_border` · `--iv_popover-max-w` · `--iv_popover-min-w` · `--iv_radius` · `--iv_shadow-md` · `--iv_spacing-xs` · `--iv_surface-raised` · `--iv_z-dropdown`

See the [token reference](/foundations/tokens.md) for values.

### CSS hooks

`.iv-cm-panel` · `.iv-cm-trigger` · `.iv-longpress` · `.iv-menu` · `.iv-ready`

## Accessibility

| Keys | Action |
| --- | --- |
| `Shift+F10 / Menu` | Opens the menu at the trigger. |
| `Arrow up / down` | Moves between items. |
| `Arrow right / left` | Opens or closes a submenu. |
| `Enter / Space` | Activates the focused item. |
| `Escape` | Closes the menu and returns focus to the trigger. |

- The panel uses `role="menu"` and items use `role="menuitem"`.
- Opening moves focus to the first item; closing restores the previous focus.
- Clicks outside the panel close it.

## Related

- [Menu](/components/menu.md)
- [Popover](/components/popover.md)
- [Dialog](/components/dialog.md)
- [Tooltip](/components/tooltip.md)