Context Menu

A native-feeling context menu in the top layer. Attach it directly to any element with {@attach contextMenu(snippet, options)} and nest cascading submenus with {@attach contextSubmenu(snippet)}. Supports pointer coordinates, touch long-press with haptics, keyboard triggers (ContextMenu / Shift+F10), safe diagonal corridor navigation, and collision-aware flipping.

Installation

Install the context menu layer package.

pnpm add @sv-layer/context-menu

Basic

Activate the button with a click, tap, Enter, or Space. Right-click, long press, and Shift+F10 also open the menu.

Last action: Idle

The first example includes its theme import. Additional examples omit decorative styles where noted; use the package theme or global surface styles.

Styling

Headless architecture: works without CSS, comes with an optional theme.

approachhow it works
theme.css (Plug & Play)
import "@sv-layer/context-menu/theme.css";
Dark menu surface with cascading submenu layout and separators.
CSS VariablesThe engine publishes --tt-available-width, --tt-available-height and --tt-transform-origin for anchored surfaces. Override theme properties with a global surface selector or configuration class.
Custom classPass class="my-context-menu" in root or submenu options.

Dynamic data per item

Each row passes a file to the menu. Select a command to see which file it targets.

Select a file to inspect its actions.

Root Options

Configuration options for contextMenu(snippet, options).

OptionTypeDefaultDescription
contentSnippet<[close, data, point]>—Menu content snippet; receives close(), data, and invocation point.
dataany | (point: Point) => any—Data passed as 2nd parameter; functions receive the invocation coordinates.
side"top" | "bottom" | "left" | "right""bottom"Preferred placement side relative to trigger or click point.
align"start" | "center" | "end" | "left" | "right""start"Alignment on the cross axis.
offsetnumber2Gap in pixels between click coordinates and the menu surface.
alignOffsetnumber2Offset along the alignment axis.
paddingnumber8Minimum boundary padding from viewport edges.
closeOnSelectbooleantrueWhether clicking an item closes the entire context menu tree.
closeOnScrollbooleantrueWhether window or container scroll closes the menu.
longPressDurationnumber500Touch hold duration in milliseconds before opening.
vibratebooleantrueWhether to emit haptic feedback (15ms) on touch trigger.
disabledbooleanfalseWhen true, disables custom context menu and allows browser default.
classstring—Custom CSS class for the menu surface container.
labelstring—Accessible name (aria-label) for the menu.
idstring—Custom HTML id applied to the surface element.
onopen(point: Point) => void—Callback fired when context menu opens, receiving click coordinates.
onclose() => void—Callback fired when context menu closes.
onopenchange(open: boolean) => void—Callback fired on open state change.

Submenu Options

Configuration options for contextSubmenu(snippet, options).

OptionTypeDefaultDescription
contentSnippet<[close, data]>—Submenu content snippet; receives close() (closes entire menu tree) and data.
dataT | () => T—Data passed to the submenu snippet.
side"right" | "left" | "top" | "bottom""right"Preferred placement side relative to the sub-trigger button; flips automatically on collision.
align"start" | "center" | "end" | "left" | "right""start"Alignment along the sub-trigger item.
offsetnumber-4Offset from trigger; negative values provide a seamless hover bridge.
alignOffsetnumber-4Offset along the alignment axis.
paddingnumber8Minimum boundary padding from viewport edges.
disabledbooleanfalseWhether the submenu trigger is disabled.
closeOnSelectbooleantrueWhether clicking an item closes the entire menu hierarchy.
labelstring—Accessible name (aria-label) for the submenu.
classstring—Custom CSS class for the submenu surface container.
idstring—Custom HTML id applied to the submenu surface element.
onopen() => void—Callback fired when submenu opens.
onclose() => void—Callback fired when submenu closes.
onopenchange(open: boolean) => void—Callback fired on open state change.

Attachment & Handle API

The object returned by contextMenu() functions as an attachment and a reactive handle.

Property / MethodTypeDefaultDescription
isOpenboolean—Reactive boolean flag ($state). True whenever the context menu is open.
open(point?, fromKeyboard?)(point?: Point | MouseEvent | Touch | null, fromKeyboard?: "first" | "last" | null) => void—Programmatically opens context menu at virtual point coordinates.
close(focusTrigger?)(focusTrigger?: boolean) => void—Closes context menu and restores focus.
toggle(point?)(point?: Point | MouseEvent | Touch | null) => void—Toggles open/closed at coordinates.
update(config)(config: ContextMenuConfig) => void—Updates menu configuration reactively.
<script lang="ts">
	import { contextMenu } from "@sv-layer/context-menu";
	import "@sv-layer/context-menu/theme.css";

	const menu = contextMenu(menuContent);
</script>

{#snippet menuContent(close: () => void, data: unknown, point: { x: number; y: number })}
	<div class="menu-box">
		<div class="coords">At: {Math.round(point.x)}, {Math.round(point.y)}</div>
		<button onclick={() => { console.log("Inspect"); close(); }}>Inspect</button>
		<button onclick={close}>Close</button>
	</div>
{/snippet}

<div class="zone" role="button" tabindex="0" aria-label="Context target" {@attach menu}>
	Right-click, press Shift+F10, or touch and hold
</div>
<button onclick={() => menu.open({ x: 200, y: 200 })}>Open at (200, 200)</button>

Snippet Parameters

Parameters received by context menu content snippets: snippet(close, data, point).

ParameterTypeDefaultDescription
close() => void—Callback to programmatically close the entire context menu tree.
dataT—Resolved data payload passed to the menu.
pointPoint—Coordinates { x: number, y: number } in viewport client space where the menu was invoked.

Keyboard and limitations

Use a focusable trigger for ContextMenu / Shift+F10. Arrow keys wrap across available items; Home/End and typeahead select items. ArrowRight opens a submenu and ArrowLeft returns to its parent. Escape closes one level and restores focus. Touch long-press defaults to 500 ms and cancels when moving or scrolling; verify it on physical devices. Native Popover API support is required.