Skip to content
Design System
Contact

Tooltip

Short labels for icon buttons and shortcuts, on hover and keyboard focus.

ComponentsRadix Tooltip

Playground

Hover or focus the button. The delay is set on a local TooltipProvider; the app-wide provider uses 250ms, and moving between triggers skips the delay.

Preview

Props

Side
Align
Delay
Side offset
example.tsxtsx
1import { Share2 } from "lucide-react"
2import { Button } from "@/components/ui/button"
3import { Kbd } from "@/components/ui/kbd"
4import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip"
5
6<TooltipProvider delayDuration={250}>
7  <Tooltip>
8    <TooltipTrigger asChild>
9      <Button variant="outline" size="icon" aria-label="Share">
10        <Share2 />
11      </Button>
12    </TooltipTrigger>
13    <TooltipContent sideOffset={4}>
14      Share
15      <Kbd>⇧⌘S</Kbd>
16    </TooltipContent>
17  </Tooltip>
18</TooltipProvider>

States

Trigger states with the bubble drawn in place. A tooltip names or explains its trigger; it never carries the only copy of an error.

States
  • Defaultrest
  • Share
    Hover:hover + delay
  • Share ⇧⌘S
    Focusno delay on focus
  • Saving changes…
    Loadingaria-busy
  • Only owners can share
    Disabledspan wrapper
  • Sync failed 2 min ago
    Erroraria-invalid
  • Copied
    Successdata-state=success

Patterns

Labels for an icon toolbar, a reason on a disabled button, and full text for names that only get a tooltip when they are actually truncated.

Icon toolbar with shortcuts

Hover one button, then slide along the row.

Explain a disabled button

Add a title before publishing

Full text for truncated names
Column width

API

Built on Radix Tooltip. A TooltipProvider is mounted once in the app shell.

PropTypeDefaultDescription
TooltipProvider delayDurationnumber250 (app)Hover delay before opening, in ms. Focus opens immediately.
TooltipProvider skipDelayDurationnumber300Window in which moving to another trigger skips the delay.
open / onOpenChangeboolean / (open: boolean) => void—Control it, e.g. to show only when text is truncated.
TooltipContent side"top" | "right" | "bottom" | "left""top"Preferred side. Flips when there is no room.
TooltipContent align"start" | "center" | "end""center"Alignment along the trigger.
TooltipContent sideOffsetnumber0Gap from the trigger in px. 4 reads better on icon buttons.
TooltipTrigger asChildboolean—Use the child as the trigger. It must be focusable and forward refs.

Accessibility

Keyboard

Focus the trigger and show the tooltip
Tab
Dismiss without moving focus
Esc

Semantics and ARIA

  • Opens on hover and on keyboard focus. The content has role="tooltip" and the trigger points to it with aria-describedby while it is open.
  • A tooltip is a description, not a name: icon buttons still need their own aria-label, usually the same words.
  • Touch devices have no hover, so tooltips must not hold essential information. Put errors, prices and instructions on the page.
  • Keep it short and non-interactive. Links or buttons inside belong in a popover or hover card.
  • Disabled buttons don’t receive pointer or focus events. Wrap them in a focusable span, or use aria-disabled on a focusable button instead.
  • The bubble stays open while the pointer moves onto it (WCAG 1.4.13 hoverable) and Esc dismisses it (dismissible).