What is Tooltip?

A tooltip is a short piece of text that pops up next to an element when the pointer rests on it or when it receives keyboard focus, and goes away when either ends. It names or explains a control without adding permanent text to the layout. The classic case is an icon-only button in a toolbar, where the tooltip says "Bold" or "Copy link" and often shows the keyboard shortcut.

When to use it

• Labeling icon-only buttons, and showing their keyboard shortcuts.
• Revealing truncated text, such as a long file name cut off with an ellipsis.
• Brief supplementary hints that experienced users do not need.
• Not for essential information, interactive content like links or buttons, or long explanations. Touch devices have no hover, so anything important must be visible or one tap away. Use a popover for rich or interactive content.

Accessibility

In the WAI-ARIA tooltip pattern the popup has role="tooltip" and the trigger references it with aria-describedby, so the text is read as a description after the control's name. The tooltip must appear on keyboard focus as well as hover, and never receives focus itself. WCAG 1.4.13, Content on Hover or Focus, adds three rules:

• Dismissible: Escape hides the tooltip without moving focus.
• Hoverable: the pointer can move onto the tooltip without it disappearing.
• Persistent: it stays until the user moves away, dismisses it, or the information is no longer valid; it does not time out.

A tooltip does not replace an accessible name. An icon-only button still needs aria-label or visually hidden text; the tooltip is the visual equivalent for sighted users. Common failures follow from these rules: tooltips on disabled buttons, which cannot receive focus, tooltips that cover the control they describe, and tooltips used as the only label for a form field.

How to build one in React

import { CopyIcon } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip"

export function CopyLinkButton() {
  return (
    <TooltipProvider delay={400}>
      <Tooltip>
        <TooltipTrigger render={<Button variant="ghost" size="icon" aria-label="Copy link" />}>
          <CopyIcon />
        </TooltipTrigger>
        <TooltipContent>Copy link</TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

A short open delay, around 300 to 500ms, keeps tooltips from flickering as the pointer crosses a toolbar. A shared provider lets neighboring tooltips open instantly once one is showing. Keep the text to a few words and do not repeat a visible label; a button that already says Save does not need a Save tooltip. MiniDev's Tooltip is built on Base UI, which handles the ARIA wiring, Escape, hover bridging and positioning. For richer previews on hover, see HoverCard in the overlays category.