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 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.
| approach | how it works |
|---|---|
| theme.css (Plug & Play) | import "@sv-layer/context-menu/theme.css"; |
| CSS Variables | The 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 class | Pass class="my-context-menu" in root or submenu options. |
Select a file to inspect its actions.
Root Options
Configuration options for contextMenu(snippet, options).
| Option | Type | Default | Description |
|---|---|---|---|
content | Snippet<[close, data, point]> | — | Menu content snippet; receives close(), data, and invocation point. |
data | any | (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. |
offset | number | 2 | Gap in pixels between click coordinates and the menu surface. |
alignOffset | number | 2 | Offset along the alignment axis. |
padding | number | 8 | Minimum boundary padding from viewport edges. |
closeOnSelect | boolean | true | Whether clicking an item closes the entire context menu tree. |
closeOnScroll | boolean | true | Whether window or container scroll closes the menu. |
longPressDuration | number | 500 | Touch hold duration in milliseconds before opening. |
vibrate | boolean | true | Whether to emit haptic feedback (15ms) on touch trigger. |
disabled | boolean | false | When true, disables custom context menu and allows browser default. |
class | string | — | Custom CSS class for the menu surface container. |
label | string | — | Accessible name (aria-label) for the menu. |
id | string | — | 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).
| Option | Type | Default | Description |
|---|---|---|---|
content | Snippet<[close, data]> | — | Submenu content snippet; receives close() (closes entire menu tree) and data. |
data | T | () => 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. |
offset | number | -4 | Offset from trigger; negative values provide a seamless hover bridge. |
alignOffset | number | -4 | Offset along the alignment axis. |
padding | number | 8 | Minimum boundary padding from viewport edges. |
disabled | boolean | false | Whether the submenu trigger is disabled. |
closeOnSelect | boolean | true | Whether clicking an item closes the entire menu hierarchy. |
label | string | — | Accessible name (aria-label) for the submenu. |
class | string | — | Custom CSS class for the submenu surface container. |
id | string | — | 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 / Method | Type | Default | Description |
|---|---|---|---|
isOpen | boolean | — | 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).
| Parameter | Type | Default | Description |
|---|---|---|---|
close | () => void | — | Callback to programmatically close the entire context menu tree. |
data | T | — | Resolved data payload passed to the menu. |
point | Point | — | 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.