Tooltip
A tooltip component built on the native Popover API and CSS anchor positioning
Installation
Usage
Basic Usage
A basic tooltip that appears on hover or focus. Tooltip is a wiring container: it generates the content id, anchor name and delay, then provides them to TooltipTrigger / TooltipContent through context — no element cloning, the trigger is always an explicit TooltipTrigger.
"use client";
import { Tooltip, TooltipContent, TooltipTrigger } from "@/ui";
export default function TooltipBasicDemo() {
return (
<div className="flex items-center justify-center gap-8 py-8">
<Tooltip>
<TooltipTrigger>Hover me</TooltipTrigger>
<TooltipContent>Tooltip content</TooltipContent>
</Tooltip>
<Tooltip delay={300}>
<TooltipTrigger>Hover me too</TooltipTrigger>
<TooltipContent>Another tooltip</TooltipContent>
</Tooltip>
</div>
);
}
Imperative Control
Assemble the parts manually with matching id and anchorName, then control the popover imperatively for advanced scenarios like guided tours.
"use client";import { useRef } from "react";import { TooltipContent, TooltipTrigger } from "@/ui";export default function TooltipImperativeDemo() { const contentRef = useRef<HTMLDivElement>(null); return ( <div className="flex flex-col items-center gap-4 py-8"> <TooltipTrigger popoverId="imperative-tip" anchorName="--imperative-tip"> Hover Trigger </TooltipTrigger> <TooltipContent id="imperative-tip" anchorName="--imperative-tip" ref={contentRef} > Imperatively controlled tooltip </TooltipContent> <div className="flex gap-2"> <button type="button" onClick={() => contentRef.current?.showPopover()} className="px-4 py-2 text-sm border rounded hover:bg-primary-accent" > Open </button> <button type="button" onClick={() => contentRef.current?.hidePopover()} className="px-4 py-2 text-sm border rounded hover:bg-primary-accent" > Close </button> </div> </div> );}API Reference
High-level Components
Ready-to-use composite component.
Tooltip
A wiring container: generates a content id and an anchor name, then provides them (plus delay) to TooltipTrigger / TooltipContent through context. Renders nothing itself and never clones children.
| Prop | Type | Default | Description |
|---|---|---|---|
children | React.ReactNode | - | A TooltipTrigger and a TooltipContent pair |
delay | number | 100 | Delay in milliseconds before hiding tooltip |
Composable Components
TooltipTrigger
The trigger button with built-in hover and focus show/hide logic. Inside a Tooltip it inherits the wiring from context; standalone, pass popoverId / anchorName explicitly. Any element can be assembled from the parts instead — TooltipTrigger is just the ready-made button.
| Prop | Type | Default | Description |
|---|---|---|---|
popoverId | string | - | The content element id to show/hide; falls back to the Tooltip context |
anchorName | string | - | CSS anchor name set on the trigger, matched by the content's positionAnchor; falls back to the Tooltip context |
delay | number | 100 | Hide delay in milliseconds; falls back to the Tooltip context |
className | ClassNameValue | - | Custom CSS class |
style | React.CSSProperties | - | Custom inline styles, merged with the anchor name |
...props | React.ComponentProps<"button"> | - | Supports all native button props (except className, style) |
TooltipContent
The tooltip bubble rendered inline with popover="manual" (the top layer escapes ancestor overflow clipping) and anchor positioning.
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | - | Element id referenced by the trigger's popoverId; falls back to the Tooltip context |
anchorName | string | - | Trigger's anchor name, applied as positionAnchor; falls back to the Tooltip context |
delay | number | 100 | Hide delay in milliseconds for pointer interactions; falls back to the Tooltip context |
className | ClassNameValue | - | Custom CSS class |
style | React.CSSProperties | - | Custom inline styles, merged with the anchor styles |
ref | React.Ref<HTMLDivElement> | - | Ref to the popover element for imperative showPopover() and hidePopover() calls |
...props | React.ComponentProps<"div"> | - | Supports all native div props (except className, style, id) |
Notes
- Built on the native Popover API and CSS anchor positioning (
anchor-name/position-anchor/position-area), with no manual positioning fallback. - Anchored above the trigger by default, with
position-try-fallbacks: flip-block, flip-inlinehandling overflow automatically — no direction prop needed. - The content keeps itself open while the pointer is over it;
showPopover()on an already open popover is a no-op. - Multiple
showPopover()calls won't reopen, andhidePopover()closes immediately.