Tooltip

Example

<span data-slean="tooltip">
	<button type="button" data-slean="button" data-slean-part="trigger" aria-describedby="tooltip-save">
		Save
	</button>
	<span id="tooltip-save" role="tooltip" popover="hint" data-slean-part="content">
		Saves the draft (Ctrl+S)
	</span>
</span>
<span data-slean="tooltip" data-slean-side="bottom">
	<button type="button" data-slean="button" data-variant="outline" data-slean-part="trigger"
		aria-describedby="tooltip-share">Share</button>
	<span id="tooltip-share" role="tooltip" popover="hint" data-slean-part="content">
		Copies a read-only link
	</span>
</span>

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

<span data-slean="tooltip">
	<button type="button" data-slean="button" data-slean-part="trigger" aria-describedby="tooltip-save">
		Save
	</button>
	<span id="tooltip-save" role="tooltip" popover="hint" data-slean-part="content">
		Saves the draft (Ctrl+S)
	</span>
</span>

Why this implementation exists

A tooltip has two hard parts: rendering above everything, and the timing. The first is the platform’s since the Popover API: the content is in the top layer, never clipped by an overflow container, and popover="hint" closes other hints without closing an open menu. What the platform has no trigger for is hover with a delay, keyboard focus and Escape.

Those need listeners, but not one per tooltip. The behavior registers one handler per event type with the shared router and keeps one pending timer and one open tooltip for the whole page, which is also how the delay is skipped when the pointer moves from one trigger to the next.

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="tooltip"; 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/tooltip/register';

import '@svelte-lean/styles/tooltip.css';

Wrap the trigger and the content in a root. The trigger names the content with aria-describedby, so its text is announced as the trigger’s description even without JavaScript.

Keep the content to text. A link or a button inside a tooltip cannot be reached from the keyboard; use a Popover for interactive content.

Anatomy

Runtime profile

The tooltip registers five handlers (pointerover, pointerout, focusin, focusout, keydown) with the shared router and keeps two variables for the page: the open tooltip and one timer. A thousand tooltips keep one listener per type (tests/tooltip.test.ts).

Accessibility contract

• The trigger’s aria-describedby names the content; role="tooltip" on the content.
• Keyboard focus shows the tooltip at once; a mouse click that focuses the trigger does not.
• The content stays open while the pointer is over it and Escape hides it without moving focus (WCAG 1.4.13).
• Touch pointers are ignored: a long press is not a tooltip, and the description is still announced.

Keyboard

Platform features

Without JavaScript

The content never shows. The trigger keeps its accessible description through aria-describedby, so screen reader users still hear the text.

Server rendering

Render the markup as is. A popover is not rendered until it is shown, so the content costs no layout.

Before hydration

Before the behavior loads, hovering shows nothing. The registration attaches no per-root state, so the first hover after hydration works.

Styling

tooltip.css draws the bubble from the inverted tokens, places it with position-area on the chosen side, anchors it through anchor-name scoped to the root, and fades it in. The tokens it reads:

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

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

Compatibility notes

The Popover API is Baseline 2024. popover="hint" and the source option of showPopover() are Chromium-first; elsewhere the content falls back to a manual popover the behavior hides itself. Anchor positioning is in Chrome and Safari; without it the content is centered in the top layer.

Examples

Sides and delay

data-slean-side places the content on one of four sides with position-area, and position-try-fallbacks flips it when there is no room. data-slean-delay sets the hover delay of one root.

<!-- Placement and delay are attributes on the root. -->
<span data-slean="tooltip" data-slean-side="right" data-slean-delay="300">…</span>

Testing

• packages/primitives/tests/tooltip.test.ts Vitest: delays, hover onto the content, neighbours, touch, Escape, 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/tooltip/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/tooltip/contract.ts typed constants: name, tier, base, parts, options, events
• packages/primitives/src/tooltip/behavior.ts the behavior definition
• packages/primitives/src/tooltip/register.ts the registration module
• packages/styles/css/tooltip.css the optional stylesheet