---
title: "Menu"
description: "A vertical list of commands, options, or links."
category: "Overlays"
slug: menu
url: /components/menu
since: "0.2.0"
status: "stable"
---

# Menu

A vertical list of commands, options, or links.

## Import

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

## Preview

A header, items with shortcuts, and a separator.

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

	let last = $state('none');

	const entries: MenuEntry[] = [
		{ type: 'header', id: 'project', label: 'Project' },
		{ type: 'item', id: 'open', item: { label: 'Open', shortcut: '⏎' } },
		{ type: 'item', id: 'duplicate', item: { label: 'Duplicate', shortcut: '⌘D' } },
		{ type: 'separator', id: 'sep' },
		{ type: 'item', id: 'archive', item: { label: 'Archive' } },
		{ type: 'item', id: 'delete', item: { label: 'Delete', disabled: true } }
	];

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

<div class="stack">
	<div class="surface">
		<Menu {entries} label="Project actions" onclick={handle} />
	</div>
	<p class="readout">last action: {last}</p>
</div>

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

	.surface {
		width: 260px;
		border: 1px solid var(--iv_border);
		border-radius: var(--iv_radius-sm);
		background: var(--iv_surface-raised);
	}

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

## Usage

- `entries` is a typed list of headers, items, separators, and submenus.
- `semantic="listbox"` switches the roles for selection menus; pair it with `multiselect`.
- `onclick` receives the native event and the activated entry.

## Examples

### Listbox

Selection semantics with selected rows and a multiple mode.

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

	let selected = $state<string[]>(['logs']);

	const options = [
		{ id: 'logs', label: 'Logs' },
		{ id: 'metrics', label: 'Metrics' },
		{ id: 'traces', label: 'Traces' }
	];

	const entries = $derived<MenuEntry[]>(
		options.map((option) => ({
			type: 'item' as const,
			id: option.id,
			item: { label: option.label, selected: selected.includes(option.id) }
		}))
	);

	function handle(_event: MouseEvent, entry: MenuEntry) {
		if (entry.type !== 'item') return;
		selected = selected.includes(entry.id)
			? selected.filter((id) => id !== entry.id)
			: [...selected, entry.id];
	}
</script>

<div class="stack">
	<div class="surface">
		<Menu {entries} semantic="listbox" multiselect label="Signals" onclick={handle} />
	</div>
	<p class="readout">selected: {selected.join(', ') || '—'}</p>
</div>

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

	.surface {
		width: 260px;
		border: 1px solid var(--iv_border);
		border-radius: var(--iv_radius-sm);
		background: var(--iv_surface-raised);
	}

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

### Submenu

A nested menu that opens on hover or the right arrow key.

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

	let last = $state('none');

	const entries: MenuEntry[] = [
		{ type: 'item', id: 'rename', item: { label: 'Rename' } },
		{
			type: 'submenu',
			id: 'share',
			label: 'Share',
			children: [
				{ type: 'item', id: 'link', item: { label: 'Copy link' } },
				{ type: 'item', id: 'email', item: { label: 'Email invite' } }
			]
		},
		{ type: 'item', id: 'details', item: { label: 'Details' } }
	];

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

<div class="stack">
	<div class="surface">
		<Menu {entries} label="Item actions" onclick={handle} />
	</div>
	<p class="readout">last action: {last}</p>
</div>

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

	.surface {
		width: 260px;
		border: 1px solid var(--iv_border);
		border-radius: var(--iv_radius-sm);
		background: var(--iv_surface-raised);
	}

	.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` | `MenuEntry[]` | `[]` | Menu structure: headers, items, separators, and submenus. |
| `semantic` | `MenuSemantic` | `'menu'` | ARIA role: a command menu or a listbox. |
| `multiselect` | `boolean` | `false` | Allows several items to show as selected. |
| `emptyLabel` | `string` | `''` | Text shown when there are no entries. |
| `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. |

### Events

| Event | Handler type | Description |
| --- | --- | --- |
| `click` | `(e: MouseEvent, entry: MenuEntry) => void` | Called with the native event and the activated entry. |

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

### Types

#### `MenuSemantic`

ARIA role used for the menu container.

```ts
type MenuSemantic = 'menu' | 'listbox';
```

#### `MenuItem`

A single actionable menu row.

```ts
interface MenuItem {
	label: string;
	icon?: Icon;
	shortcut?: string;
	trailingIcon?: Icon;
	disabled?: boolean;
	dim?: boolean;
	selected?: boolean;
	active?: boolean;
	onclick?: (e: MouseEvent) => void;
	onmouseenter?: (e: MouseEvent) => void;
}
```

#### `MenuEntry`

One row of the menu structure, including headers and separators.

```ts
type MenuEntry =
	| { type: 'header'; id: string; label: string }
	| { type: 'separator'; id: string }
	| { type: 'item'; id: string; item: MenuItem }
	| {
			type: 'submenu';
			id: string;
			label: string;
			icon?: Icon;
			children: MenuEntry[];
			disabled?: boolean;
	  };
```

### Tokens used

`--iv_border` · `--iv_bracket` · `--iv_disabled-opacity` · `--iv_ease-out` · `--iv_font-mono` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_menu-lead-size` · `--iv_radius` · `--iv_radius-sm` · `--iv_reverse-bg` · `--iv_reverse-fg` · `--iv_shadow-sm` · `--iv_spacing-md` · `--iv_spacing-sm` · `--iv_spacing-xs` · `--iv_submenu-min-w` · `--iv_surface-hover` · `--iv_surface-raised` · `--iv_text-body` · `--iv_text-label` · `--iv_text-sm` · `--iv_text-xs` · `--iv_tracking-wide` · `--iv_transition-fast` · `--iv_z-dropdown`

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

### CSS hooks

`.iv-active` · `.iv-checkbox` · `.iv-checked` · `.iv-dim` · `.iv-disabled` · `.iv-empty` · `.iv-item` · `.iv-label` · `.iv-leading` · `.iv-menu` · `.iv-section-header` · `.iv-selected` · `.iv-separator` · `.iv-shortcut` · `.iv-submenu` · `.iv-submenu-item` · `.iv-trailing`

## Accessibility

- Headers and separators are visual structure; items carry `menuitem` or `option`.
- Selected items expose `aria-checked` in menu mode and `aria-selected` in listbox mode.
- Items are not in the tab order by design — place the menu in `ContextMenu` or move focus yourself.

## Related

- [ContextMenu](/components/context-menu.md)
- [Select](/components/select.md)
- [Popover](/components/popover.md)
- [Shortcut](/components/shortcut.md)