Skip to content
iv-ui v0.3.0

Menu

since 0.2.0

A vertical list of commands, options, or links.

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

Basic

A header, items with shortcuts, and a separator.

last action: none

Source· svelte Show Hide
<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>
  • 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.

Listbox

Selection semantics with selected rows and a multiple mode.

Logs
Metrics
Traces

selected: logs

Source· svelte Show Hide
<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.

last action: none

Source· svelte Show Hide
<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>
import { Menu } from '@elluzion/iv-ui';

Props

7 props · 1 events · 0 snippets
PropTypeDefaultDescription
entries MenuEntry[][]Menu structure: headers, items, separators, and submenus.
semantic MenuSemantic'menu'ARIA role: a command menu or a listbox.
multiselect booleanfalseAllows 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

EventHandler typeDescription
onclick(e: MouseEvent, entry: MenuEntry) => voidCalled 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.

type MenuSemantic = 'menu' | 'listbox';
MenuItem

A single actionable menu row.

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.

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;
	  };
  • 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.
Class 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
iv-ui
↑ ↓ navigate ↵ open esc close minisearch · 482 records