Hovercard
Interactive card on hover or focus: links, avatars, actions. It shares the
positioning engine with Tooltip, but the contract is different: role="dialog", non-modal, focus can enter.
Installation
Install the hovercard layer package.
pnpm add @sv-layer/hovercard Tapping does not open a hovercard. For content that opens on tap, use 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/hovercard/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. |
| Tailwind / Custom class | Pass class="bg-neutral-900 border border-neutral-800 rounded-xl p-4" in config. |
Options
Configuration options for hovercard(options).
| Option | Type | Default | Description |
|---|---|---|---|
content | Snippet<[T, close?]> | — | Interactive card content snippet. Receives optional data and close callback. |
data | T | () => T | — | Argument for content, evaluated dynamically on open. |
label | string | — | Accessible name (aria-label) for the dialog. Defaults to the accessible name of the trigger. |
side | "top" | "right" | "bottom" | "left" | "bottom" | Placement side relative to trigger. Automatically flips on collision. |
align | "start" | "center" | "end" | "center" | Alignment on the cross axis. |
offset | number | 8 | Gap between trigger and card 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. |
delay | number | 500 | Delay in milliseconds before opening. |
closeDelay | number | 120 | Grace period before closing after pointer exits corridor. |
group | string | "" | Shared delay group with tooltips and hovercards. |
closeOnScroll | boolean | true | Whether scrolling ancestors automatically closes the hovercard. |
disabled | boolean | false | Disables hovercard activation. |
class | string | — | Custom CSS class for styling the hovercard surface. |
id | string | — | Custom HTML id applied to the surface element. |
onopen | (data: T) => void | — | Callback fired when hovercard opens, receiving resolved data. |
onclose | () => void | — | Callback fired when hovercard closes. |
onopenchange | (open: boolean) => void | — | Callback fired on open state change. |
Attachment & Handle API
The object returned by hovercard() functions as an attachment and a reactive handle.
| Property / Method | Type | Default | Description |
|---|---|---|---|
isOpen | boolean | — | Reactive boolean flag ($state). True whenever the hovercard is open. |
open() | () => void | — | Programmatically opens the hovercard immediately (skips open delay). |
close() | () => void | — | Programmatically closes the hovercard immediately. |
toggle() | () => void | — | Toggles open/closed state. |
<script lang="ts">
import { hovercard } from "@sv-layer/hovercard";
import "@sv-layer/hovercard/theme.css";
const card = hovercard({
content: userPreview,
side: "bottom",
align: "start",
});
</script>
{#snippet userPreview(data: unknown, close?: () => void)}
<div class="user-card">
<p>Gordon Freeman</p>
<button onclick={close}>Dismiss</button>
</div>
{/snippet}
<button class:active={card.isOpen} {@attach card}>
@gordon ({card.isOpen ? "Open" : "Closed"})
</button>
<button onclick={() => card.toggle()}>Toggle</button>Snippet Parameters
Parameters received by interactive content snippets: snippet(data, close).
| Parameter | Type | Default | Description |
|---|---|---|---|
data | T | — | Resolved data payload passed to the hovercard. |
close | () => void | — | Optional callback to programmatically close the hovercard from inside interactive elements. |
Why it is not a tooltip
Shared positioning engine, separate surfaces and accessibility models.
| property | tooltip() | hovercard() |
|---|---|---|
| role | tooltip | dialog |
| Trigger ARIA | aria-describedby | aria-haspopup + aria-expanded |
| Dialog name | — | label or the accessible name of the trigger |
| focus | never enters | Tab moves inside |
| Escape | close | close + focus back to the trigger |
| touch | off | not opened by tap |
| modal | no | no: no trap, no scroll lock |
- Non-modal by design: the page stays interactive.
- Hover uses the same corridor and close delay as tooltip.
- Both layers resolve positioning through
@sv-layer/core.