Dropdown
A menu in the top layer. Attach it directly to any trigger element with {@attach dropdown(snippet)}. Arrows, Home/End and typeahead navigate focus with zero wrapper overhead.
Installation
Install the dropdown layer package.
pnpm add @sv-layer/dropdown 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/dropdown/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-dropdown-surface" in the config object. |
Options
Configuration options for dropdown(snippet, options).
| Option | Type | Default | Description |
|---|---|---|---|
content | Snippet<[close, data]> | — | Menu content snippet. Receives close() callback and optional data. |
data | T | () => T | — | Data passed as second argument to content; functions resolve on open. |
side | "top" | "bottom" | "left" | "right" | "bottom" | Preferred side relative to trigger. Automatically flips on collision. |
align | "start" | "center" | "end" | "left" | "right" | "start" | Alignment on the cross axis. |
offset | number | 6 | Gap between trigger and menu surface in pixels. |
alignOffset | number | 0 | Offset along the alignment axis in pixels. |
padding | number | 8 | Minimum boundary padding from viewport edges. |
arrow | boolean | false | Whether to render an indicator arrow. |
closeOnSelect | boolean | true | Whether selecting any menuitem closes the menu automatically. |
disabled | boolean | false | Disables the dropdown trigger. |
label | string | — | Accessible name (aria-label) for the menu. |
class | string | — | Custom CSS class for the menu surface container. |
id | string | — | Custom HTML id applied to the surface element. |
onopen | () => void | — | Callback fired when menu opens. |
onclose | () => void | — | Callback fired when menu closes. |
onopenchange | (open: boolean) => void | — | Callback fired on open state change. |
Attachment & Handle API
The object returned by dropdown() functions as an attachment and a reactive handle.
| Property / Method | Type | Default | Description |
|---|---|---|---|
isOpen | boolean | — | Reactive boolean flag ($state). True whenever the dropdown menu is open. |
open(fromKeyboard?) | (fromKeyboard?: "first" | "last" | null) => void | — | Programmatically opens the dropdown, with optional initial item focus. |
close(focusTrigger?) | (focusTrigger?: boolean) => void | — | Programmatically closes the dropdown, with optional trigger focus restoration. |
toggle() | () => void | — | Toggles the dropdown open/closed. |
update(config) | (config: DropdownConfig) => void | — | Updates dropdown configuration reactively. |
<script lang="ts">
import { dropdown } from "@sv-layer/dropdown";
import "@sv-layer/dropdown/theme.css";
const menu = dropdown(menuContent, { align: "start" });
</script>
{#snippet menuContent(close: () => void, data: unknown)}
<button onclick={() => { console.log("Edit"); close(); }}>Edit</button>
<button onclick={() => { console.log("Duplicate"); close(); }}>Duplicate</button>
<button onclick={() => { console.log("Delete"); close(); }}>Delete</button>
{/snippet}
<button class:active={menu.isOpen} {@attach menu}>
Actions ({menu.isOpen ? "Open" : "Closed"})
</button>
<button onclick={() => menu.open("first")}>Open via code</button>Snippet Parameters
Parameters received by menu content snippets: snippet(close, data).
| Parameter | Type | Default | Description |
|---|---|---|---|
close | () => void | — | Callback to programmatically close the menu from custom buttons or items. |
data | T | — | Resolved data payload passed to the dropdown menu snippet. |
What is next
The menu is feature complete for a flat list.
- Submenus within a dropdown that open on hover or
ArrowRight, with a safe corridor. - Virtualised lists that drive focus via
aria-activedescendant.
How it works
Headless attachment, top-layer menu panel, and the shared anchor engine.
- Attached directly to any trigger element via
{@attach dropdown(snippet, options)}. Zero wrapper divs. Automatically injectsaria-haspopup="menu",aria-expandedandaria-controls. - Pressing
EnterorSpaceon the trigger opens the menu and focuses the first item per WAI-ARIA APG. - The menu is
popover="manual": native top-layer placement, no clipping byoverflowortransformancestors. - Positioning is the core
AnchoredPositionengine. It flips on the main axis, shifts on the cross axis, and publishes--tt-*variables. - Outside clicks are caught on
pointerdownand checked with trigger/content containment during the document capture phase. - Selecting any menu item automatically closes the menu via
closeOnSelect(can be overridden withdata-keep-open). focusoutcloses the menu when focus leaves;Escapecloses and returns focus to the trigger. When the dropdown is inside a modal, a secondEscapecloses the modal.- Items get
role="menuitem"andtabindex="-1". Arrows wrap,Home/Endjump, printable keys typeahead for 500 ms, disabled items are skipped,Tabcloses and moves on.