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

Profile card

Mouse: hover @Be1zebub to open the card. Keyboard: Tab to @Be1zebub, then Tab again to reach Open profile. Escape returns focus to the trigger.

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.

approachhow it works
theme.css (Plug & Play)
import "@sv-layer/hovercard/theme.css";
Optional card dialog theme with dark panel background, border, and shadows.
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.
Tailwind / Custom classPass class="bg-neutral-900 border border-neutral-800 rounded-xl p-4" in config.

Options

Configuration options for hovercard(options).

OptionTypeDefaultDescription
contentSnippet<[T, close?]>—Interactive card content snippet. Receives optional data and close callback.
dataT | () => T—Argument for content, evaluated dynamically on open.
labelstring—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.
offsetnumber8Gap between trigger and card in pixels.
alignOffsetnumber0Offset along the alignment axis in pixels.
paddingnumber8Minimum boundary padding from viewport edges.
arrowbooleanfalseWhether to render an aligned indicator arrow.
delaynumber500Delay in milliseconds before opening.
closeDelaynumber120Grace period before closing after pointer exits corridor.
groupstring""Shared delay group with tooltips and hovercards.
closeOnScrollbooleantrueWhether scrolling ancestors automatically closes the hovercard.
disabledbooleanfalseDisables hovercard activation.
classstring—Custom CSS class for styling the hovercard surface.
idstring—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 / MethodTypeDefaultDescription
isOpenboolean—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).

ParameterTypeDefaultDescription
dataT—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.

propertytooltip()hovercard()
roletooltipdialog
Trigger ARIAaria-describedbyaria-haspopup + aria-expanded
Dialog name—label or the accessible name of the trigger
focusnever entersTab moves inside
Escapecloseclose + focus back to the trigger
touchoffnot opened by tap
modalnono: 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.