[ [UI.24] Components ] Tooltip

Tooltip

> A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.

Import

[ [0x5B] IMPORT ]

1import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip"

Preview

[ [0x00] TOOLTIP ]

1<TooltipProvider>
2  <Tooltip>
3    <TooltipTrigger asChild>
4      <Button variant="outline">&gt; HOVER ME</Button>
5    </TooltipTrigger>
6    <TooltipContent>
7      <p>Add to library</p>
8    </TooltipContent>
9  </Tooltip>
10</TooltipProvider>

Variants

[ [0x00] ICON BUTTON ]

1<TooltipProvider>
2  <Tooltip>
3    <TooltipTrigger asChild>
4      <Button variant="outline" size="icon" aria-label="Add new item">
5        <Plus className="h-4 w-4" />
6      </Button>
7    </TooltipTrigger>
8    <TooltipContent>
9      <p>Add new item</p>
10    </TooltipContent>
11  </Tooltip>
12</TooltipProvider>

[ [0x00] DESTRUCTIVE ACTION ]

1<TooltipProvider>
2  <Tooltip>
3    <TooltipTrigger asChild>
4      <Button variant="destructive" size="icon" aria-label="Delete permanently">
5        <Trash2 className="h-4 w-4" />
6      </Button>
7    </TooltipTrigger>
8    <TooltipContent>
9      <p>Delete permanently</p>
10    </TooltipContent>
11  </Tooltip>
12</TooltipProvider>

[ [0x00] WITH KEYBOARD SHORTCUT ]

1<TooltipProvider>
2  <Tooltip>
3    <TooltipTrigger asChild>
4      <Button variant="ghost" size="icon" aria-label="Save">
5        <Save className="h-4 w-4" />
6      </Button>
7    </TooltipTrigger>
8    <TooltipContent>
9      <p>
10        Save <kbd className="ml-1 bg-muted border border-border px-1">⌘S</kbd>
11      </p>
12    </TooltipContent>
13  </Tooltip>
14</TooltipProvider>

[ [0x00] MULTIPLE TOOLTIPS ]

1<TooltipProvider>
2  <div className="flex gap-2">
3    <Tooltip>
4      <TooltipTrigger asChild>
5        <Button variant="outline" size="icon" aria-label="Edit">
6          <Edit className="h-4 w-4" />
7        </Button>
8      </TooltipTrigger>
9      <TooltipContent>
10        <p>Edit</p>
11      </TooltipContent>
12    </Tooltip>
13    <Tooltip>
14      <TooltipTrigger asChild>
15        <Button variant="outline" size="icon" aria-label="Delete">
16          <Trash2 className="h-4 w-4" />
17        </Button>
18      </TooltipTrigger>
19      <TooltipContent>
20        <p>Delete</p>
21      </TooltipContent>
22    </Tooltip>
23    <Tooltip>
24      <TooltipTrigger asChild>
25        <Button variant="outline" size="icon" aria-label="Settings">
26          <Settings className="h-4 w-4" />
27        </Button>
28      </TooltipTrigger>
29      <TooltipContent>
30        <p>Settings</p>
31      </TooltipContent>
32    </Tooltip>
33  </div>
34</TooltipProvider>

[ [0x00] CUSTOM DELAY ]

1<TooltipProvider delayDuration={300}>
2  <Tooltip>
3    <TooltipTrigger asChild>
4      <Button variant="secondary">&gt; DELAYED TOOLTIP</Button>
5    </TooltipTrigger>
6    <TooltipContent>
7      <p>This tooltip has a 300ms delay</p>
8    </TooltipContent>
9  </Tooltip>
10</TooltipProvider>

API Reference

[ [0x00] API REFERENCE ]

Prop	Type	Default	Description
delayDuration	`number`	`700`	The duration from when the mouse enters a tooltip trigger until the tooltip opens (in ms). Set on TooltipProvider.
skipDelayDuration	`number`	`300`	How long a user has to enter another trigger without delay after closing a tooltip (in ms). Set on TooltipProvider.
open	`boolean`	`undefined`	Control the open state of the tooltip.
onOpenChange	`(open: boolean) => void`	`undefined`	Event handler called when the open state changes.
defaultOpen	`boolean`	`false`	The initial open state in uncontrolled mode.
sideOffset	`number`	`4`	The distance in pixels from the trigger.

Accessibility

[ [0x58] A11Y ]

Implements ARIA tooltip pattern with role='tooltip'
TooltipTrigger has aria-describedby pointing to the tooltip content
Tooltip appears on hover and keyboard focus
Escape key dismisses the tooltip
Automatically positions to stay in viewport
Essential for icon-only buttons to provide accessible labels
Respects prefers-reduced-motion for animations
Should not contain interactive content (use Popover instead)

When to Use

[ [0xE9] USAGE GUIDANCE ]

✓ Use Tooltip when:

• Icon-only buttons need accessible labels (edit, delete, settings icons)
• Abbreviations or truncated text need full context (hover to see full name)
• Providing additional context on hover (why is this disabled?)
• Showing keyboard shortcuts (Save: ⌘S)
• Short supplemental information (1-2 sentences max)

✗ Don't use when:

• Information is critical to task completion (show it directly in UI)
• Content needs to be interactive or clickable (use Popover instead)
• Text is longer than 2-3 sentences (use Popover or Dialog)
• Primary mobile experience (touch devices don't have hover)
• User needs to copy text from tooltip (use Popover for selectable text)

Tooltip vs Popover:

• Tooltip: Non-interactive, hover/focus, short text (1-2 lines)
• Popover: Interactive, click to open, complex content with links/buttons
• Tooltip: Auto-dismisses on mouse leave, ESC key
• Popover: Stays open until user closes it
• Always wrap multiple tooltips in single TooltipProvider for performance
• Keep delay short (300-700ms) for responsive feel

1<TooltipProvider>

2 <Tooltip>

3 <TooltipTrigger asChild>

4 <Button variant="outline">> HOVER ME</Button>

5 </TooltipTrigger>

6 <TooltipContent>

7 <p>Add to library</p>

8 </TooltipContent>

9 </Tooltip>

10</TooltipProvider>