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

Demo

Click the trigger, use arrows, press Escape, or click outside.

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/dropdown/theme.css";
Dark panel surface with frosted glass blur, menu item styles, and entrance transitions.
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-dropdown-surface" in the config object.

Keyboard + typeahead

Open with Enter or ArrowDown, then type v for Vite or s for Svelte. After a click, press ArrowDown before typing. Arrows skip Sapper.

Options

Configuration options for dropdown(snippet, options).

OptionTypeDefaultDescription
contentSnippet<[close, data]>—Menu content snippet. Receives close() callback and optional data.
dataT | () => 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.
offsetnumber6Gap between trigger and menu surface in pixels.
alignOffsetnumber0Offset along the alignment axis in pixels.
paddingnumber8Minimum boundary padding from viewport edges.
arrowbooleanfalseWhether to render an indicator arrow.
closeOnSelectbooleantrueWhether selecting any menuitem closes the menu automatically.
disabledbooleanfalseDisables the dropdown trigger.
labelstring—Accessible name (aria-label) for the menu.
classstring—Custom CSS class for the menu surface container.
idstring—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 / MethodTypeDefaultDescription
isOpenboolean—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).

ParameterTypeDefaultDescription
close() => void—Callback to programmatically close the menu from custom buttons or items.
dataT—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 injects aria-haspopup="menu", aria-expanded and aria-controls.
  • Pressing Enter or Space on 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 by overflow or transform ancestors.
  • Positioning is the core AnchoredPosition engine. It flips on the main axis, shifts on the cross axis, and publishes --tt-* variables.
  • Outside clicks are caught on pointerdown and checked with trigger/content containment during the document capture phase.
  • Selecting any menu item automatically closes the menu via closeOnSelect (can be overridden with data-keep-open).
  • focusout closes the menu when focus leaves; Escape closes and returns focus to the trigger. When the dropdown is inside a modal, a second Escape closes the modal.
  • Items get role="menuitem" and tabindex="-1". Arrows wrap, Home/End jump, printable keys typeahead for 500 ms, disabled items are skipped, Tab closes and moves on.