Tooltip
A popup that appears when an element is hovered or focused, showing a hint for sighted users.
Base UI
Shadcn UIInstallation
npx shadcn@latest add @redpanda/tooltippnpm dlx shadcn@latest add @redpanda/tooltipyarn dlx shadcn@latest add @redpanda/tooltipbunx shadcn@latest add @redpanda/tooltipnubx shadcn@latest add @redpanda/tooltipaube dlx shadcn@latest add @redpanda/tooltipPositioning
When to use
Tooltips are supplementary visual labels for controls that already have an independent purpose and accessible name. They are not a way to deliver instructions to touch or screen reader users.
If an information icon exists to open its own popup, use Popover with a named title and description.
openOnHover on PopoverTrigger can retain optional hover access while native activation works with keyboard
and touch. Keep essential field instructions visible and associate them with the input using aria-describedby.
See the Base UI usage guidelines and infotip guidance.
Usage
<TooltipProvider> <Tooltip> <TooltipTrigger render={<Button type="submit">Save</Button>} /> <TooltipContent>Save</TooltipContent> </Tooltip></TooltipProvider>Props
Props
TooltipContent
arrow?boolean
Whether to show the arrow.
booleantrueKeyboard interactions
| Key | Action |
|---|---|
Tab to TooltipTrigger |
Opens the tooltip (keyboard-focus trigger). |
Shift+Tab off the trigger |
Closes the tooltip. |
Escape |
Closes the tooltip without moving focus. |
| Mouse hover / blur | Opens after delayDuration, closes immediately on leave. |
Accessibility
- Tooltips are visual-only hints. They do not provide
aria-describedbyor replace the trigger’s accessible name. Give icon controls anaria-labelthat closely matches the visible hint. - Use a native interactive trigger through
render. Keep its original action and keyboard behavior; do not add a focusable wrapper solely to expose a disabled control’s reason. Put important reasons in associated visible text. - Use Popover, not Tooltip, when opening information is the trigger’s purpose. Give the popover a
PopoverTitleandPopoverDescription; native activation must work without hover. - Wrap multiple tooltips in a single
TooltipProvider— Base UI shares adelay/timeoutpool so rapid-hover tooltips don’t re-fire the delay.
Controlled vs uncontrolled
Uncontrolled — typical case:
<Tooltip> <TooltipTrigger render={<Button type="submit">Save</Button>} /> <TooltipContent>Save</TooltipContent></Tooltip>Controlled — coordinate the visibility of a visual hint; this does not announce new information to assistive technology:
const [open, setOpen] = useState(true);
<Tooltip open={open} onOpenChange={setOpen}> <TooltipTrigger render={<Button type="submit">Save</Button>} /> <TooltipContent>Save</TooltipContent></Tooltip>;