Tooltip
A short hint on hover or focus, for naming an icon-only control or adding a detail the user can do without.
import from ~/components/ui/tooltip
On a control
Tooltip / TooltipTrigger / TooltipContent
The trigger takes asChild so the tooltip attaches to the real button rather than wrapping it in a span. Hover it, or Tab to it: focus opens the tooltip too.
On an icon-only button
icon-only
The tooltip is the hint, never the name. The button still carries an aria-label, because a screen reader user should not have to hover to learn what it does.
Side
side
Default is top. Radix flips the tooltip automatically when it would leave the viewport, so set side only when the default collides with something.
Rules
Do
Keep it to a few words. A tooltip hints, it does not hold content.
Attach it to a focusable control with asChild, so keyboard and hover both open it.
Give an icon-only trigger an aria-label as well. The tooltip is a hint, not the accessible name.
Let the tooltip sit at z-tooltip, above every other layer. Never pass a numeric z class.
Don't
Never make a tooltip the only way to convey something. It is hidden by default and touch users never see it.
Never put interactive content inside one: no links, no buttons, no form controls. It closes before the user gets there.
Do not wrap a disabled button. A disabled element fires no pointer events, so the tooltip never opens.
Do not use a tooltip where a popover belongs. Anything the user needs to read at length or click into is a popover.