Tooltip
Introduction
A contextual overlay component used to display descriptive, helpful, or supplementary information when users hover their cursor or move keyboard focus onto an active trigger element. Excellent for explaining dense button icons, clarify system policies, or describing visual charts.
For tooltip that need to show multiline content, use HoverCard.
Hydration & Interactive Behavior
Because the Tooltip must dynamically calculate its viewport coordinates on hover and track active keyboard focus, it hydrates as an active client-side island by default. If a static, non-interactive layout placeholder is preferred, set "interactive": false to suppress client-side javascript loading.
Usage
These configurations represent exactly how page-builder block items are constructed.
1. Information Policy Popover (Top Placement)
An information tooltip useful for explaining company guidelines, cancellation policies, or technical jargon.
{
"type": "tooltip",
"content": "Free cancellation up to 24 hours before check-in.",
"triggerText": "Cancellation Policy",
"placement": "top",
"showArrow": true
}
2. Helpful Quick-Info Tag (Right Placement)
A compact, accented tooltip pointing to the right of its trigger. Ideal for describing visual icons, settings controls, or metadata terms.
{
"type": "tooltip",
"content": "Syncs files across workspace nodes instantly.",
"triggerText": "Database Sync",
"placement": "right",
"showArrow": true
}
Props
| Property | Type | Default | Description / Supported Options |
|---|---|---|---|
Trigger Text (triggerText) | string | - | The plain-text label of the button rendered on-screen that triggers the tooltip on hover or focus. |
Hover Content (content) | string | - | The descriptive help text shown inside the floating tooltip overlay. |
Show Arrow (showArrow) | boolean | true | When true, renders a small pointing triangle indicator aligning the tooltip card directly to its trigger. |
Preferred Placement (placement) | select | "top" | Ideal viewport boundary side to render. Flips to opposite side automatically if there is not enough room. • Options: "top", "bottom", "left", "right". |
Open Delay (openDelay) | number | 100 | Delay in milliseconds before showing the tooltip after hovering starts. |
Close Delay (closeDelay) | number | 100 | Delay in milliseconds before hiding the tooltip after mouse-out. |
Enable Hydration (interactive) | boolean | true | When true, hydrates the component as a client island to compute viewport coordinates and manage hover/focus listeners. |
Accessibility & Technical Execution
- Focus Roving and Keyboard Support: Tooltips strictly comply with WCAG 1.4.13 guidelines. Focusing the trigger button via keyboard tab immediately displays the overlay card. Moving the pointer over the tooltip's own card content (such as a link inside) keeps it open.
- Escape Close Bindings: Pressing the physical Escape button on a keyboard immediately dismisses the active tooltip, returning active screen focus cleanly to the trigger button.
- Auto-Flipping Geometry: The interactive layout manager calculates trigger positioning on the fly. If a tooltip is set to
"placement": "top"but sits near the upper edge of the screen, it automatically flips to"bottom"to guarantee it never renders off-screen. - Trigger Element Merging: With
asChildenabled, the tooltip merges all its required event listeners, data states, andaria-describedbyfocus fields directly onto the nested child element. WithoutasChild, the trigger is nested inside an accessible<div tabindex="0">wrapper.