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 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/tooltip/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-zinc-900 text-white rounded px-2.5 py-1 text-xs" in config. Functional resets (popover & arrow position) remain
active. |
Options
Configuration options passed to tooltip(options).
| Option | Type | Default | Description |
|---|---|---|---|
text | string | () => string | — | Plain text content or dynamic text getter evaluated on open. |
content | Snippet<[T]> | — | Rich content snippet rendered into the single global top-layer surface. |
data | T | () => 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. |
offset | number | 8 | Gap between trigger and tooltip 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 in milliseconds before closing after pointer leaves. |
group | string | "" | Shared delay group. Moving between elements in a warm group opens instantly. |
disabled | boolean | false | Disables tooltip activation. |
class | string | — | Custom CSS class for styling the tooltip surface. |
id | string | — | 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 / Method | Type | Default | Description |
|---|---|---|---|
isOpen | boolean | — | 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).
| Parameter | Type | Default | Description |
|---|---|---|---|
data | T | — | 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.
| event | what happens |
|---|---|
| pointerenter | open instantly in a warm group, otherwise after delay |
| pointerleave | corridor toward the content, otherwise close after closeDelay |
| pointerdown | tooltip closes |
| focusin + :focus-visible | open instantly |
| focusout | close |
| Escape | close |
| ancestor scroll | close, except the scroll caused by focus |
| touch | tooltip 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.