Tooltip
Short, non-interactive supplementary information for a trigger.
Tooltip provides a short hint on hover or keyboard focus. Use a focusable trigger that forwards its ref and event handlers, such as a native button or Puzzle Button.
Import
import { Tooltip } from "@puzzle-ui/ui";Basic usage
Hover over the button or reach it with Tab. The tooltip closes on pointer leave, blur, or Escape.
Position
position requests one of four sides. The popup can fall back to another side when there is not enough space.
Alignment, offset, and exit delay
align aligns the popup along the trigger's edge. offset is the gap in pixels; exitDelay is the delay in milliseconds before closing on pointer leave.
Controlled visibility
Use open with onOpenChange when visibility belongs to application state. Use defaultOpen instead to start an uncontrolled tooltip open.
API
| Prop | Type | Default | Description |
|---|---|---|---|
trigger | ReactElement | Required | Single trigger accepting DOM attributes and a ref. |
children | ReactNode | Required | Non-interactive hint content. |
position | "top" | "right" | "bottom" | "left" | "bottom" | Preferred popup side. |
align | "start" | "center" | "end" | "center" | Popup alignment along the trigger. |
offset | number | 8 | Gap from the trigger in pixels. |
exitDelay | number | 100 | Pointer-leave delay in milliseconds. |
open | boolean | - | Controlled visibility. |
defaultOpen | boolean | false | Initial uncontrolled visibility. |
onOpenChange | (open: boolean) => void | - | Called when visibility changes are requested. |
className | string | - | Additional class on the tooltip content. |
triggerClassName | string | - | Additional class merged onto the trigger. |
Accessibility
The popup has role="tooltip" and is linked to its trigger with aria-describedby; an existing description relationship is preserved. Keep a meaningful accessible name on the trigger itself, and do not put essential information only in a tooltip.
Tooltip content must not be interactive: keyboard users cannot reach it because it closes when focus leaves the trigger. Use Popover for links, buttons, form controls, or a close button.