Context menu

Example

<div data-slean="context-menu">
	<ul data-slean-part="target" tabindex="0" aria-label="Files">
		<li tabindex="-1">report.pdf</li>
		<li tabindex="-1">budget.xlsx</li>
	</ul>
	<div id="context-files" popover role="menu" aria-label="File actions" data-slean="menu"
		data-slean-part="menu">
		<button type="button" role="menuitem" data-slean-value="open">Open</button>
		<button type="button" role="menuitem" data-slean-value="rename">Rename</button>
		<hr />
		<button type="button" role="menuitem" data-slean-value="delete">Delete</button>
	</div>
</div>

<script lang="ts">
	// With @svelte-lean/vite the register imports are injected for the static markers.
	import '@svelte-lean/styles/popover.css';
	import '@svelte-lean/styles/menu.css';
	import '@svelte-lean/styles/context-menu.css';
	import type { ContextMenuOpenDetail } from '@svelte-lean/primitives/context-menu';
	import type { MenuSelectDetail } from '@svelte-lean/primitives/menu';
	import { on } from 'svelte/events';

	let file = $state('');

	// slean:open names the element the menu was requested on; remember which file it was.
	function opening(event: Event) {
		const { target } = (event as CustomEvent<ContextMenuOpenDetail>).detail;
		file = target.closest('li')?.textContent ?? '';
	}

	function chosen(event: Event) {
		const { value } = (event as CustomEvent<MenuSelectDetail>).detail;
		console.log(value, file);
	}
</script>

<div data-slean="context-menu" {@attach (node) => on(node, 'slean:open', opening)}>
	<ul data-slean-part="target" tabindex="0" aria-label="Files">
		<li tabindex="-1">report.pdf</li>
		<li tabindex="-1">budget.xlsx</li>
	</ul>
	<div
		popover
		role="menu"
		aria-label="File actions"
		data-slean="menu"
		data-slean-part="menu"
		{@attach (node) => on(node, 'slean:select', chosen)}
	>
		<button type="button" role="menuitem" data-slean-value="open">Open</button>
		<button type="button" role="menuitem" data-slean-value="rename">Rename</button>
		<hr />
		<button type="button" role="menuitem" data-slean-value="delete">Delete</button>
	</div>
</div>

Why this implementation exists

Every way of asking for a context menu already arrives as one event: contextmenu is dispatched for a secondary click, for the context-menu key and Shift+F10, and for a long press where the platform supports it. What the browser shows by default is its own menu. A context menu replaces it: cancel the event, open a menu popover at the pointer.

After the opening there is nothing new to build. The menu is the Menu primitive: a popover in the top layer with light dismiss and Escape from the platform, and arrows, typeahead and activation from the menu behavior. The context menu adds one shared listener and the placement, which keeps the menu inside the viewport with one layout read per opening.

Usage

Install @svelte-lean/primitives for the behavior and @svelte-lean/styles for the stylesheet. With @svelte-lean/vite the registration is injected for every static data-slean="context-menu"; without it, import the register module once.

npm install @svelte-lean/primitives

pnpm add @svelte-lean/primitives

yarn add @svelte-lean/primitives

bun add @svelte-lean/primitives

import '@svelte-lean/primitives/context-menu/register';

import '@svelte-lean/styles/popover.css';
import '@svelte-lean/styles/menu.css';
import '@svelte-lean/styles/context-menu.css';

Wrap the area and a menu root: target on the area (focusable, so the keyboard can ask for the menu) and menu on a data-slean="menu" popover named with aria-label.

Listen to slean:open to learn which element the menu was requested on, for example the row or the file under the pointer, and fill or adjust the menu there. Cancelling it lets the browser show its own menu.

Anatomy

Runtime profile

The context menu registers one contextmenu handler with the shared router; the menu registers its own. Opening reads the menu's box once to keep it inside the viewport. A thousand targets keep one listener (tests/context-menu.test.ts).

Accessibility contract

• The menu is an ARIA menu named by aria-label; its keyboard is the menu contract.
• Shift+F10 and the context-menu key open it under the focused element, so the menu is reachable without a pointer.
• Opening moves focus to the first item; Escape or a choice returns focus to the element that had it.
• A context menu is hidden by nature: offer the same actions somewhere visible, a toolbar or a row menu, for people who never right-click.

Keyboard

Platform features

Without JavaScript

The browser's own context menu appears; the menu popover never opens.

Server rendering

Render the markup as is; the menu is closed and costs no layout.

Before hydration

Before the behavior loads, a right click shows the browser's menu. The first request after hydration opens the menu.

Styling

context-menu.css sets the target's cursor and the menu's transform origin, and removes the anchor placement so the inline position applies; the surface and the rows come from popover.css and menu.css. The tokens it reads:

State selectors the stylesheet targets, all from the platform or ARIA: :dir(rtl).

Compatibility notes

The contextmenu event is widely available, but Safari on iOS does not dispatch it for a long press: touch users of an iPhone or iPad cannot open the menu. The Popover API is Baseline 2024.

Testing

• packages/primitives/tests/context-menu.test.ts Vitest: pointer and keyboard placement, viewport, RTL, slean:open, 1000 roots
• apps/playground/tests/primitives/layout.spec.ts Playwright: the splitter and the context menu in Chrome, with axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)

Source

• packages/primitives/src/context-menu/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/context-menu/contract.ts typed constants: name, tier, base, parts, options, events
• packages/primitives/src/context-menu/behavior.ts the behavior definition
• packages/primitives/src/context-menu/register.ts the registration module
• packages/styles/css/context-menu.css the optional stylesheet