Hover card

Example

<div>
	Reviewed by
	<span data-slean="hover-card">
		<a href="/people/ada" data-slean-part="trigger">Ada Lovelace</a>
		<div popover="hint" data-slean-part="content">
			<p><strong>Ada Lovelace</strong> · Analyst, London</p>
			<p>Notes on the analytical engine, 1843.</p>
			<a href="/people/ada/notes">Read the notes</a>
		</div>
	</span>
	on 28 September.
</div>

<script lang="ts">
	// With @svelte-lean/vite the register import is injected for the static data-slean="hover-card".
	import '@svelte-lean/styles/hover-card.css';

	let { person }: { person: { name: string; role: string; href: string } } = $props();
</script>

<span data-slean="hover-card">
	<a href={person.href} data-slean-part="trigger">{person.name}</a>
	<div popover="hint" data-slean-part="content">
		<p><strong>{person.name}</strong> · {person.role}</p>
		<a href="{person.href}/notes">Read the notes</a>
	</div>
</span>

Why this implementation exists

A tooltip describes its trigger in a few words; a hover card previews where its trigger leads, with a picture, details and links of its own. That makes it interactive content, so it cannot be a description (aria-describedby) and it must be reachable by keyboard.

The platform provides the pieces: a hint popover in the top layer, which does not close an open menu, and showPopover({ source }), which makes the trigger the invoker so the card follows it in the focus order. The behavior adds what has no trigger in HTML: a hover delay, keeping the card open while the pointer crosses onto it or focus is inside it, and Escape that returns focus without reopening the card.

Usage

Install @svelte-lean/primitives for the behavior and @svelte-lean/styles for the stylesheet. With @svelte-lean/vite the registration is injected for every static data-slean="hover-card"; without it, import the register module once.

npm install @svelte-lean/primitives

pnpm add @svelte-lean/primitives

yarn add @svelte-lean/primitives

bun add @svelte-lean/primitives

import '@svelte-lean/primitives/hover-card/register';

import '@svelte-lean/styles/hover-card.css';

Put the trigger and, right after it, the content in the root. The trigger works on its own: the card only previews its destination, since touch users never see it.

Fill the card on the server, or on the popover’s toggle event when its content is expensive.

Anatomy

Runtime profile

The hover card registers five handlers (pointerover, pointerout, focusin, focusout, keydown) with the shared router and keeps three variables for the page: the open card, one timer and the card Escape dismissed. A thousand cards keep one listener per type (tests/hover-card.test.ts).

Accessibility contract

• The card is supplementary: what it shows is also where the trigger leads.
• Keyboard focus on the trigger shows the card at once; Tab moves into it because the trigger is its invoker, and the card follows the trigger in the DOM as well.
• Escape closes the card; from inside it, focus returns to the trigger and the card stays closed until focus leaves.
• Touch pointers are ignored: a tap follows the link.

Keyboard

Platform features

Without JavaScript

The card never shows; the trigger is a working link.

Server rendering

Render the markup as is; the card is hidden until shown.

Before hydration

Before the behavior loads, hovering shows nothing. The first hover after hydration works on the server's markup.

Styling

hover-card.css draws the card surface, anchors it below the trigger's inline start (or on another side), slides it in, and keeps the platform's centered placement where anchor positioning is missing. The tokens it reads:

State selectors the stylesheet targets, all from the platform or ARIA: :popover-open.

Variant attributes: data-slean-side (top, left, right).

Compatibility notes

The Popover API is Baseline 2024. popover="hint" and the source option of showPopover() are Chromium-first; elsewhere the card is a manual popover the behavior hides itself, still after its trigger in the focus order. Anchor positioning is in Chrome and Safari.

Testing

• packages/primitives/tests/hover-card.test.ts Vitest: delays, hover onto the card, one at a time, touch, Escape and focus, 1000 roots
• apps/playground/tests/primitives/widgets.spec.ts Playwright: tooltip, toast, tree, range slider and number field in Chrome, with axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)

Source

• packages/primitives/src/hover-card/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/hover-card/contract.ts typed constants: name, tier, base, parts, options, events
• packages/primitives/src/hover-card/behavior.ts the behavior definition
• packages/primitives/src/hover-card/register.ts the registration module
• packages/styles/css/hover-card.css the optional stylesheet