Tooltip
Short, supplemental text on hover and keyboard focus.
Installation
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"Import @commenda/pathfinder/styles.css once after host CSS. Styles are precompiled with Tailwind v4; consumers need no Tailwind scanning. Interactive callbacks belong in client components in Next.js App Router.
Usage
import { Tooltip, TooltipProvider } from '@commenda/pathfinder/tooltip';
import { IconButton } from '@commenda/pathfinder/icon-button';
import { Download01Icon } from '@commenda/pathfinder/icons/Download01Icon';
<TooltipProvider>
<Tooltip
content="Download receipt"
trigger={
<IconButton label="Download receipt" tooltip={false}>
<Download01Icon />
</IconButton>
}
/>
</TooltipProvider>;API reference
| Prop | Type | Behavior |
|---|---|---|
triggerRequired | ReactElement<any, string | React.JSXElementConstructor<any>> | Required; must forward its ref and event props |
contentRequired | string | Required noninteractive text |
title | string | Optional title and shortcut chip |
shortcut | string | Optional title and shortcut chip |
side | "top"|"bottom"|"left"|"right"|"inline-end"|"inline-start" | top; collision-aware |
align | "start"|"end"|"center" | center |
showArrow | boolean | false |
sideOffset | number | 6; 11 with arrow |
disabled | boolean | Disables the tooltip, not its trigger |
openConditional | boolean | Controlled / uncontrolled visibility |
defaultOpen | boolean | Controlled / uncontrolled visibility |
onOpenChangeConditional | (open: boolean) => void | Required with open |
portalContainer | HTMLElement|ShadowRoot|RefObject<HTMLElement | ShadowRoot | null>|null | Optional portal destination |
Mount TooltipProvider once per region for the 300 ms neighbor window. Hover opens after 100 ms; keyboard focus opens immediately. Escape closes it, and the pointer can move onto its content. Give the trigger its own accessible name. When wrapping IconButton, set tooltip= to avoid two hints. Use adjacent help for essential information and disabled reasons.
Examples
Title
Shortcut
Placement
Read the design guidance before using these components.
Design rules
Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.
Tooltip — 252:57
- TOOLTIP-01: Supplemental, noninteractive text only. Essential instructions, errors, validation and required steps stay on the page. Links and buttons belong in Popover.
- TOOLTIP-02: Open after 100 ms hover, immediately on keyboard focus or for a neighboring tooltip within 300 ms. Use TooltipProvider around a region. Escape closes; the pointer can enter the popup without closing it. Open for as long as hover or focus remains.
- TOOLTIP-03: Icon-only controls need an accessible name that matches their tooltip. Do not repeat an already visible label. Field help uses a separate info control beside its label. Shortcut chips supplement another discoverable shortcut reference.
- TOOLTIP-04: Plain copy: sentence case, no period, ideally one line. Titles explain a metric or status. More than two lines belongs on the page. Pearl 1000, white Copy/12, 6 px radius, 8/12 px padding, menu elevation; 240 px maximum width, 320 with a title. Title/body gap 2; shortcut gap 8, chip height 16, pearl 900, radius 4. Arrow 10×5, off by default. Top placement flips as space requires; offsets 6 or 11 with arrow.