ui/components/tooltip

Tooltip

Minimal tooltip with hover delay and terminal styling. Built on the Popover primitive with full 4-side positioning and collision avoidance. Shows contextual information on hover without clipping by overflow ancestors.

Preview

tsx

1 import { Tooltip } from "@/components/ui/tooltip";2 3 export default function TooltipBasicExample() {4   return (5     <div className="flex items-center gap-6">6       <Tooltip content="Shorthand tooltip">7         <button8           type="button"9           className="border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"10         >11           hover me12         </button>13       </Tooltip>14 15       <Tooltip>16         <Tooltip.Trigger>17           <button18             type="button"19             className="border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"20           >21             compound22           </button>23         </Tooltip.Trigger>24         <Tooltip.Content>25           Custom tooltip with <strong>rich content</strong>26         </Tooltip.Content>27       </Tooltip>28     </div>29   );30 }31

Installation

$pnpm exec dgadd add ui/tooltip

[Installs to]src/components/ui/tooltip[Item]ui/tooltip

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 import { Tooltip } from "@/components/ui/tooltip";2 3 export default function TooltipBasicExample() {4   return (5     <div className="flex items-center gap-6">6       <Tooltip content="Shorthand tooltip">7         <button8           type="button"9           className="border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"10         >11           hover me12         </button>13       </Tooltip>14 15       <Tooltip>16         <Tooltip.Trigger>17           <button18             type="button"19             className="border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"20           >21             compound22           </button>23         </Tooltip.Trigger>24         <Tooltip.Content>25           Custom tooltip with <strong>rich content</strong>26         </Tooltip.Content>27       </Tooltip>28     </div>29   );30 }31

Examples

Open State (static)

Preview

tsx

1 import { Tooltip } from "@/components/ui/tooltip";2 3 // Controlled `open` with no setter pins the surface open, so the open state4 // stays reviewable in a documentation page or a screenshot. `defaultOpen` is5 // not enough here: it seeds uncontrolled state that the hover tooltip's own6 // scroll dismissal then clears the moment a reader scrolls down to this7 // example. Real tooltips open on hover/focus — do not pin `open` in product8 // code.9 const TRIGGER =10   "border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0";11 12 export default function TooltipOpenExample() {13   return (14     <div className="flex flex-wrap items-center gap-16 py-14">15       <Tooltip open>16         <Tooltip.Trigger>17           <button type="button" className={TRIGGER}>18             Above19           </button>20         </Tooltip.Trigger>21         <Tooltip.Content side="top">Runs the review pipeline</Tooltip.Content>22       </Tooltip>23 24       <Tooltip open>25         <Tooltip.Trigger>26           <button type="button" className={TRIGGER}>27             Below28           </button>29         </Tooltip.Trigger>30         <Tooltip.Content side="bottom">--surface-1 fill, 1px hairline, no shadow</Tooltip.Content>31       </Tooltip>32 33       <Tooltip open>34         <Tooltip.Trigger>35           <button type="button" className={TRIGGER}>36             Right37           </button>38         </Tooltip.Trigger>39         <Tooltip.Content side="right">Mono type, tight padding</Tooltip.Content>40       </Tooltip>41     </div>42   );43 }44

Placement

Preview

tsx

1 import { Tooltip } from "@/components/ui/tooltip";2 3 export default function TooltipPlacementExample() {4   const sides = ["top", "bottom", "left", "right"] as const;5 6   return (7     <div className="flex flex-wrap items-center gap-6">8       {sides.map((side) => (9         <Tooltip key={side}>10           <Tooltip.Trigger>11             <button12               type="button"13               className="border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"14             >15               {side}16             </button>17           </Tooltip.Trigger>18           <Tooltip.Content side={side}>Tooltip on {side}</Tooltip.Content>19         </Tooltip>20       ))}21     </div>22   );23 }24

Interactive Triggers

Preview

tsx

1 "use client";2 3 import { Tooltip } from "@/components/ui/tooltip";4 5 export default function TooltipInteractiveExample() {6   return (7     <div className="flex items-center gap-6">8       <Tooltip>9         <Tooltip.Trigger>10           {(triggerProps) => (11             <button12               {...triggerProps}13               type="button"14               className="border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"15             >16               save17             </button>18           )}19         </Tooltip.Trigger>20         <Tooltip.Content>Save changes to disk</Tooltip.Content>21       </Tooltip>22 23       <Tooltip>24         <Tooltip.Trigger>25           {(triggerProps) => (26             <button27               {...triggerProps}28               type="button"29               aria-disabled="true"30               onClick={(event) => event.preventDefault()}31               className="border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0 opacity-50"32             >33               delete34             </button>35           )}36         </Tooltip.Trigger>37         <Tooltip.Content>Remove selected items</Tooltip.Content>38       </Tooltip>39     </div>40   );41 }42

API Reference

Name	Type	Default	Description
content	ReactNode	—	Shorthand: when set to renderable content, Tooltip renders children inside Tooltip.Trigger and content inside Tooltip.Content automatically. When omitted — or falsy, as in the conditional `content={isTruncated && label}` idiom — compose Tooltip.Trigger and Tooltip.Content explicitly via children.
open	boolean	—	Controlled open state.
defaultOpen	boolean	false	Initial open state for uncontrolled mode.
onOpenChange	(open: boolean) => void	—	Fired when the open state changes.
enabled	boolean	true	Disables hover/focus triggering when false (use to suppress tooltips conditionally).
delayMs	number	500	Show delay after the pointer enters the trigger; keyboard focus opens immediately.
closeDelayMs	number	150	Hide delay after pointer/focus leaves the trigger or content.
childrenrequired	ReactNode	—	Trigger element (shorthand mode) or full Tooltip.Trigger/Tooltip.Content composition.

Tooltip.Trigger

Name	Type	Default	Description
childrenrequired	ReactNode \| (props: PopoverTriggerRenderProps) => ReactNode	—	Trigger element. Pass a single element, text, or a render function, with the same render-prop and clone semantics as Popover.Trigger.

Name	Type	Default	Description
side	"top" \| "bottom" \| "left" \| "right"	"top"	Preferred side relative to the trigger.
align	"start" \| "center" \| "end"	"center"	Alignment along the chosen side.
sideOffset	number	4	Pixel gap from the trigger along the side axis.
alignOffset	number	0	Pixel offset along the alignment axis.
avoidCollisions	boolean	true	Flips to the opposite side, then cross-axis sides, then shifts within the viewport to keep the tooltip inside it.
collisionPadding	number	8	Minimum gap between the tooltip and the viewport edge.
childrenrequired	ReactNode	—	Tooltip body content.

Accessibility

Keyboard Navigation

Tooltip shows on focus and hides on blur, so Tab into the trigger reveals the tooltip. Escape dismisses the tooltip and returns focus to the trigger.

Interactive triggers with keyboard

Preview

tsx

1 "use client";2 3 import { Tooltip } from "@/components/ui/tooltip";4 5 export default function TooltipInteractiveExample() {6   return (7     <div className="flex items-center gap-6">8       <Tooltip>9         <Tooltip.Trigger>10           {(triggerProps) => (11             <button12               {...triggerProps}13               type="button"14               className="border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"15             >16               save17             </button>18           )}19         </Tooltip.Trigger>20         <Tooltip.Content>Save changes to disk</Tooltip.Content>21       </Tooltip>22 23       <Tooltip>24         <Tooltip.Trigger>25           {(triggerProps) => (26             <button27               {...triggerProps}28               type="button"29               aria-disabled="true"30               onClick={(event) => event.preventDefault()}31               className="border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0 opacity-50"32             >33               delete34             </button>35           )}36         </Tooltip.Trigger>37         <Tooltip.Content>Remove selected items</Tooltip.Content>38       </Tooltip>39     </div>40   );41 }42

Notes

Shorthand

Use the `content` prop on Tooltip root for simple text tooltips without compound nesting: `<Tooltip content="Help text"><button>…</button></Tooltip>`.

Positioning

Content supports all four sides via the `side` prop: `top` (default), `bottom`, `left`, `right`. Use `align` (`start`, `center`, `end`) for cross-axis alignment. Automatic flip and shift when content would overflow the viewport.

Portal Rendering

Content renders through the shared Portal primitive. When a PortalContainerProvider is present, Tooltip.Content uses that scoped container; otherwise it falls back to document.body. This keeps nested overlay trees in the same portal scope while still escaping overflow:hidden ancestors by default.

Conditional Display

Use the `enabled` prop to conditionally disable the tooltip without unmounting. Pairs well with useOverflowDetection — only show tooltip when content is actually truncated.

Delay

Default pointer show delay is 500ms (hover intent); keyboard focus opens immediately. The hide delay after pointer or focus leaves is 150ms. Customize them with `delayMs` and `closeDelayMs`.

Built on Popover

Tooltip is a thin wrapper around the Popover primitive with `triggerMode="hover"`. For interactive floating content, use Popover directly.

Surface

The surface (1px --border hairline, --surface-1 fill with a 1px --surface-1-highlight inner top lip, rounded-sm corners) comes from Popover.Content; Tooltip.Content only adds its max width, tight padding, and mono type. No drop shadow — the hairline plus the one-step surface lift carry the edge, which keeps the box in the same register as Menu, Select, and Dialog.

Reviewing the Open State

A hover tooltip shows nothing on a static page. Pass a controlled `open` with no setter to pin the surface open when you need the open state visible in documentation, a design review, or a visual-regression capture — see the Open State example. `defaultOpen` only seeds uncontrolled state, so hover leave or a scroll still closes it. Product code should use neither and let hover/focus drive the tooltip.

Controlled Mode

Supports `open`, `defaultOpen`, and `onOpenChange` props for programmatic control: `<Tooltip content="Help" open={showHelp} onOpenChange={setShowHelp}>...</Tooltip>`.

Source

Install via CLI: pnpm exec dgadd add ui/tooltip. Keyboard hooks are included as standalone copies. For the full experience, use --integration keys.

Highlighted source loads after this disclosure opens. Browse the source repository.

Tooltip

Installation

Usage

Examples

Open State (static)

Placement

Interactive Triggers

API Reference

Tooltip

Tooltip.Trigger

Tooltip.Content

Accessibility

Keyboard Navigation

Interactive triggers with keyboard

Notes

Shorthand

Positioning

Portal Rendering

Conditional Display

Delay

Built on Popover

Surface

Reviewing the Open State

Controlled Mode

Source

View component source (33 files)