Menu

Example

<button
	type="button"
	id="file-button"
	data-slean="button"
	data-variant="outline"
	popovertarget="file-menu"
	aria-haspopup="menu"
>
	File
</button>

<div
	id="file-menu"
	popover
	role="menu"
	aria-labelledby="file-button"
	data-slean="menu"
	data-slean-side="bottom"
	data-slean-align="start"
>
	<button type="button" role="menuitem" data-slean-value="new">New file</button>
	<a role="menuitem" href="/docs">Open…</a>
	<button type="button" role="menuitemcheckbox" aria-checked="false" data-slean-value="wrap">
		Word wrap
	</button>
	<div role="group" aria-label="Theme">
		<span data-slean-part="label">Theme</span>
		<button type="button" role="menuitemradio" aria-checked="true" data-slean-value="light">
			Light
		</button>
		<button type="button" role="menuitemradio" aria-checked="false" data-slean-value="dark">
			Dark
		</button>
	</div>
	<div role="separator"></div>
	<button type="button" role="menuitem" data-slean-value="save">
		Save <span data-slean-part="shortcut">Ctrl+S</span>
	</button>
	<button type="button" role="menuitem" data-slean-value="print" disabled>Print</button>
</div>

<script lang="ts">
	// With @svelte-lean/vite this import is injected for the static data-slean="menu" marker.
	// Without the plugin, write it yourself once; both paths register the same behavior.
	import '@svelte-lean/primitives/menu/register';
	import '@svelte-lean/styles/button.css';
	import '@svelte-lean/styles/menu.css'; // brings popover.css
</script>

<button
	type="button"
	id="file-button"
	data-slean="button"
	data-variant="outline"
	popovertarget="file-menu"
	aria-haspopup="menu"
>
	File
</button>

<div
	id="file-menu"
	popover
	role="menu"
	aria-labelledby="file-button"
	data-slean="menu"
	data-slean-side="bottom"
	data-slean-align="start"
>
	<button type="button" role="menuitem" data-slean-value="new">New file</button>
	<a role="menuitem" href="/docs">Open…</a>
	<button type="button" role="menuitemcheckbox" aria-checked="false" data-slean-value="wrap">
		Word wrap
	</button>
	<div role="group" aria-label="Theme">
		<span data-slean-part="label">Theme</span>
		<button type="button" role="menuitemradio" aria-checked="true" data-slean-value="light">
			Light
		</button>
		<button type="button" role="menuitemradio" aria-checked="false" data-slean-value="dark">
			Dark
		</button>
	</div>
	<div role="separator"></div>
	<button type="button" role="menuitem" data-slean-value="save">
		Save <span data-slean-part="shortcut">Ctrl+S</span>
	</button>
	<button type="button" role="menuitem" data-slean-value="print" disabled>Print</button>
</div>

Last slean:select on the example: No selection yet.

Why this implementation exists

A menu button is two things. Visibility, light dismiss, Escape, the top layer, focus return and aria-expanded are the Popover API's job, and the browser does them. Desktop-style keyboard behavior inside the menu is not: arrow keys between items, Home and End, typeahead, Space on a link item, closing on selection, and the checked state of checkbox and radio items. Svelte Lean adds only that second part, as one behavior shared by every menu on the page, and calls hidePopover() to close. This is the composition ADR 0001 aims at: native visibility plus a small keyboard behavior, instead of JavaScript visibility, dismiss, portal, focus, positioning and keyboard.

Usage

npm install @svelte-lean/primitives

pnpm add @svelte-lean/primitives

yarn add @svelte-lean/primitives

bun add @svelte-lean/primitives

npm install --save-dev @svelte-lean/vite

pnpm add -D @svelte-lean/vite

yarn add -D @svelte-lean/vite

bun add -d @svelte-lean/vite

npm install @svelte-lean/styles

pnpm add @svelte-lean/styles

yarn add @svelte-lean/styles

bun add @svelte-lean/styles

With the Vite plugin, every static data-slean="menu" gets import '@svelte-lean/primitives/menu/register' appended to its compiled module; without the plugin, write that import yourself once. menu.css imports popover.css itself, because a menu is a popover: the surface, the placement and the open transition live there.

// Any module that runs once on the client, for example the root layout. Safe on the server,
// idempotent, and the same module the plugin injects.
import '@svelte-lean/primitives/menu/register';

import '@svelte-lean/styles/tokens.css';
import '@svelte-lean/styles/base.css';
import '@svelte-lean/styles/menu.css'; /* imports popover.css: the surface and placement live there */

Use a menu for a list of actions or settings attached to a button, with desktop-style keyboard behavior: file menus, row actions, view options. Site navigation is a <nav> with links, not a menu. The one option keeps focus on the invoker when the popover opens:

<!-- Keep focus on the invoker when the popover opens: -->
<div id="file-menu" popover role="menu" aria-labelledby="file-button" data-slean="menu" data-slean-autofocus="none">

Anatomy

Runtime profile

The bytes in the runtime block are the production build of @svelte-lean/primitives/menu/register including the shared kernel, from packages/primitives/artifacts/size.json (1932 B brotli · 2162 B gzip). The kernel is shared: a page with tabs and menu builds to one Svelte Lean chunk of 2351 B brotli in the tabs-and-menu fixture, against 1521 B brotli for tabs alone. The three listeners (click, keydown and toggle in the capture phase) serve every menu on the page; one typeahead buffer exists for the whole page and is created on first use. There is no per-root state, no observer and no layout read; the proof page shows the listener account of this site, where tabs and menu share the click and keydown entries.

Accessibility contract

• Root: popover, role="menu", an id and aria-labelledby pointing at the invoker, which names the menu and lets the behavior find the invoker. Invoker: aria-haspopup="menu"; aria-expanded comes from popovertarget.
• Items are <button type="button"> or <a href> with role="menuitem", menuitemcheckbox or menuitemradio; checkbox and radio items carry aria-checked, radio items are grouped by the nearest role="group". Separators are role="separator".
• Focus: on open the first enabled item receives focus (or nothing with data-slean-autofocus="none"). On close (Escape, selection, Tab) the platform returns focus to the invoker for an auto popover; the behavior also focuses the invoker it finds through aria-labelledby when focus is not there, which covers popover="manual".
• Disabled: data-slean-disabled or aria-disabled="true" on the root skips routing. An item with disabled is not focusable; with aria-disabled="true" it is focusable, skipped by arrows, Home, End and typeahead, and its click is prevented.
• Editable elements inside the root keep their keys; only Escape and Tab still close the menu. Vertical only; no horizontal keys, nothing to flip under RTL.
• Development validation warns about: a root without popover, role="menu" or id; items that are not <button> or <a>; checkbox or radio items without aria-checked; data-slean-part="item" without a menuitem role.

Keyboard

Keys with Alt, Ctrl or Meta are ignored, except Escape and Tab. On the invoker, Enter and Space toggle the popover natively; ArrowDown on the invoker is not handled because the invoker is outside the root. The typeahead timeout is the default of createTypeahead() in @svelte-lean/core.

Platform features

Without JavaScript

With the Popover API the menu opens and closes, link items work, button items do nothing and movement inside is Tab-based. Without Popover API support the attribute is ignored and the content renders inline. Nothing is hidden by this: an unregistered menu is a popover with buttons in it.

Server rendering

Static HTML; the menu is closed on load and the initial aria-checked values are authored. The register module is safe to import on the server: without a document the registration waits until a browser runtime exists (packages/primitives/tests/ssr.test.ts).

Before hydration

The popover opens before any script because the browser owns visibility; keyboard movement and the checked state need the register module, which evaluates before the component code once the scripts arrive. Hydration attaches nothing to a menu root: the toggle listener is on the document, installed when the behavior registered, and the first open is the first work done for a root.

Styling

menu.css styles the rows by role, the separator, the group label and the shortcut hint, the checked mark on [aria-checked="true"], an inset focus ring for :focus-visible, and the submenu chevron (styling only; submenus are not implemented). The surface, placement and open transition come from popover.css. The tokens it reads and the states it targets:

State selectors the stylesheet targets, all from the platform or ARIA: :dir(rtl), :disabled, :focus-visible, :hover, [aria-checked="true"], [aria-disabled="true"], [aria-expanded="true"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="separator"].

Variant attributes: data-variant (danger).

Controlled integration

What exists today: the root dispatches a bubbling, cancelable slean:select CustomEvent after the checked state is updated and before the popover is hidden, with detail of type MenuSelectDetail (item, value, checked); preventDefault() keeps the menu open. For <a> items the navigation follows the click as usual; cancel the click event to stop it. closeMenu(), menuItems() and menuInvoker() from @svelte-lean/primitives/menu are the helpers. An application listens with addEventListener, as the status line under the example does.

<script lang="ts">
	import { closeMenu, type MenuSelectDetail } from '@svelte-lean/primitives/menu';

	let root: HTMLElement;
	let wrap = $state(false);

	$effect(() => {
		// slean:select bubbles from the root after aria-checked is updated and before the
		// popover is hidden; preventDefault() keeps the menu open.
		const onSelect = (event: Event) => {
			const { value, checked } = (event as CustomEvent<MenuSelectDetail>).detail;
			if (value === 'wrap') {
				wrap = checked === true;
				event.preventDefault();
			}
		};
		root.addEventListener('slean:select', onSelect);
		return () => root.removeEventListener('slean:select', onSelect);
	});
</script>

<div id="file-menu" popover role="menu" aria-labelledby="file-button" data-slean="menu" bind:this={root}>
	…
</div>
<button type="button" onclick={() => closeMenu(root)}>Close the menu from outside</button>

Compatibility notes

The menu depends on the Popover API (Baseline newly available since April 2024) for visibility and on CSS anchor positioning (Chrome 125, Safari 26; not Baseline) for placement, with the same fallbacks as Popover: inline content without the API, centered placement without anchor positioning. The behavior needs ES2022 output and composedPath(). Tested in Chromium; Firefox and WebKit runs do not exist yet. The policy is on Browser support.

Testing

• packages/primitives/tests/menu.test.ts unit tests (happy-dom with a Popover API shim): opening, keyboard, typeahead, selection, checked state, helpers, validation
• apps/playground/tests/primitives/menu.spec.ts Playwright: the real popover, top layer, light dismiss, focus restoration, typeahead timing
• apps/playground/tests/primitives/nested.spec.ts a menu inside a tab panel and tabs inside a menu
• fixtures/tabs-and-menu consumer build: both registrations ship with one kernel
• apps/playground/tests/primitives/a11y.spec.ts axe on every playground page and on open dialog, popover and menu states

Source

• packages/primitives/src/menu/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/menu/contract.ts typed constants: name, tier, base, parts, options, events
• packages/primitives/src/menu/behavior.ts the behavior definition, menuItems(), menuInvoker(), closeMenu()
• packages/primitives/src/menu/register.ts the registration module, the only side effect
• packages/primitives/src/menu/validate.ts development validation messages
• packages/styles/css/menu.css the optional stylesheet