Popover
Tap-driven anchored dialog in the top layer. Designed for arbitrary rich interactive content: forms, filters, and pickers. Non-modal by default with optional modal focus trap.
Installation
Install the popover layer package.
pnpm add @sv-layer/popover 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/popover/theme.css"; |
| Custom class | Pass class="my-popover-panel" in the config object. |
Options
Configuration options for popover(config).
| Option | Type | Default | Description |
|---|---|---|---|
content | Snippet<[data, close?]> | — | Rich dialog content snippet. Receives data and an optional close() callback. |
data | T | () => T | — | Passed to content; functions are evaluated reactively on open. |
side | "top" | "bottom" | "left" | "right" | "bottom" | Preferred placement side. Automatically flips when colliding. |
align | "start" | "center" | "end" | "center" | Alignment on the cross axis. |
offset | number | 8 | Gap between trigger and popover 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 aligned indicator arrow. |
modal | boolean | false | Traps both Tab directions and makes the background inert; does not lock body scrolling. |
autoFocus | boolean | false | Focuses the first available control. In modal mode, false focuses the surface itself. |
closeOnScroll | boolean | false | Whether scrolling ancestor containers closes the popover. |
disabled | boolean | false | Disables the popover trigger. |
label | string | — | Accessible name (aria-label) for the dialog element. |
class | string | — | Custom CSS class name for the popover surface container. |
id | string | — | Custom HTML id applied to the surface element. |
onopen | (data: T) => void | — | Callback fired when popover opens, receiving resolved data. |
onclose | () => void | — | Callback fired when popover closes. |
onopenchange | (open: boolean) => void | — | Callback fired on open state change. |
Attachment & Handle API
The object returned by popover() functions as an attachment and a reactive handle.
| Property / Method | Type | Default | Description |
|---|---|---|---|
isOpen | boolean | — | Reactive boolean flag ($state). True whenever the popover is currently open. |
open() | () => void | — | Programmatically opens the popover. |
close() | () => void | — | Programmatically closes the popover and restores focus to trigger. |
toggle() | () => void | — | Toggles the popover open/closed. |
<script lang="ts">
import { popover } from "@sv-layer/popover";
import "@sv-layer/popover/theme.css";
const pop = popover({
content: panelContent,
side: "bottom",
align: "start",
});
</script>
{#snippet panelContent(data: unknown, close?: () => void)}
<div class="popover-box">
<p>Settings panel</p>
<button onclick={close}>Save & Close</button>
</div>
{/snippet}
<button class:active={pop.isOpen} {@attach pop}>
Options {pop.isOpen ? "▲" : "▼"}
</button>
<button onclick={() => pop.close()}>Close from code</button>Snippet Parameters
Parameters received by interactive content snippets: snippet(data, close).
| Parameter | Type | Default | Description |
|---|---|---|---|
data | T | — | Resolved data payload passed to the popover. |
close | () => void | — | Optional callback to programmatically close the popover from within buttons or forms inside the panel. |
Keyboard and limitations
Tab enters a non-modal popover from its trigger; Shift+Tab returns to the trigger, and Tab from the last control continues after the trigger. Escape closes the active layer. With modal: true, both directions stay inside, the background becomes inert and autoFocus: false focuses the surface. Popover does not lock body scrolling. Use a clear label. Native Popover API support is required; tap opens the panel.