Tooltip

Positioned text layer for hints and descriptions. Features global delay groups, collision detection, and one shared top-layer surface.

Installation

Install the tooltip layer package.

pnpm add @sv-layer/tooltip

Basic

Hover or focus a trigger with the keyboard. Touch taps do not open tooltips. The examples cover text, title fallback, and a disabled tooltip.

link

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/tooltip/theme.css";
Optional dark glass theme, refined shadows, and entrance transitions.
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-zinc-900 text-white rounded px-2.5 py-1 text-xs" in config. Functional resets (popover & arrow position) remain active.

Delay group

The first button waits 500 ms. Neighbours open instantly, with no replayed animation.

Rich + shared

One snippet for every trigger; data is read when the tooltip opens.

Handle

The attachment is also a handle. isOpen is a rune, so class:active just works.

Collision

Show at bottom edge opens a preview at the viewport boundary. The tooltip flips above the trigger when there is no room below. Press Escape to close the preview.

Options

Configuration options passed to tooltip(options).

OptionTypeDefaultDescription
textstring | () => string—Plain text content or dynamic text getter evaluated on open.
contentSnippet<[T]>—Rich content snippet rendered into the single global top-layer surface.
dataT | () => T—Argument passed to content; functions are evaluated on open.
side"top" | "right" | "bottom" | "left""top"Placement side relative to trigger. Automatically flips on collision.
align"start" | "center" | "end""center"Alignment on the cross axis.
offsetnumber8Gap between trigger and tooltip 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 in milliseconds before closing after pointer leaves.
groupstring""Shared delay group. Moving between elements in a warm group opens instantly.
disabledbooleanfalseDisables tooltip activation.
classstring—Custom CSS class for styling the tooltip surface.
idstring—Custom HTML id applied to the surface element.
onopen(data: T) => void—Callback fired when tooltip opens, receiving resolved data.
onclose() => void—Callback fired when tooltip closes.
onopenchange(open: boolean) => void—Callback fired on open state change.

Attachment & Handle API

The object returned by tooltip() functions as an attachment and a reactive handle.

Property / MethodTypeDefaultDescription
isOpenboolean—Reactive boolean flag ($state). True whenever the tooltip is currently open.
open()() => void—Programmatically opens the tooltip immediately without delay.
close()() => void—Programmatically closes the tooltip immediately without closeDelay.
toggle()() => void—Toggles tooltip open or closed.
<script>
	import { tooltip } from "@sv-layer/tooltip";

	const tip = tooltip({ text: "Opened from code", arrow: true, side: "bottom" });
</script>

<div class="row">
	<button class:active={tip.isOpen} {@attach tip}>hover me</button>
	<button onclick={() => tip.open()}>tip.open()</button>
	<button onclick={() => tip.close()}>tip.close()</button>
</div>

Snippet Parameters

Parameters received by rich content snippets: snippet(data).

ParameterTypeDefaultDescription
dataT—Resolved data payload passed to the tooltip, evaluated from the data option or getter.

Behavior

Every instance handles the same input scenario the same way.

eventwhat happens
pointerenteropen instantly in a warm group, otherwise after delay
pointerleavecorridor toward the content, otherwise close after closeDelay
pointerdowntooltip closes
focusin + :focus-visibleopen instantly
focusoutclose
Escapeclose
ancestor scrollclose, except the scroll caused by focus
touchtooltip never opens
  • One tooltip per element.
  • No virtual anchor.
  • Text only: interactive content belongs to the Hovercard layer.
  • No native interestfor / popover="hint": Safari does not ship them.