Tooltip

When to UseCopy Anchor Link

• to show the name of an icon-only Button, in the words of its aria-label
• to show the shortcut of a control, in a Kbd after its name
• to name the items of a Sidebar that is collapsed to icons, through the tooltip prop of SidebarMenuButton

When Not to UseCopy Anchor Link

• for text that users need to finish a task, such as a hint or a format (write it on the page, for example in the FieldDescription of a Field)
• for the text behind an info icon (use a Popover with openOnHover)
• for content that contains a link or a Button, as focus never moves into a Tooltip (use a Popover)
• to preview the page behind a link (use a Hover Card)

See Popover for a comparison of the Popover, the Tooltip, and the Hover Card.

Avoid placing text that users need to finish a task in a Tooltip, as a tap doesn’t open a Tooltip and screen readers don’t announce one.

AnatomyCopy Anchor Link

TooltipContent renders the portal, the positioner, the popup, and the arrow that points at the trigger.

BehaviorCopy Anchor Link

A Tooltip responds to a pointer and to keyboard focus. A tap doesn’t open one.

By default, a Tooltip inside a TooltipProvider appears after the pointer has rested on its trigger for 200ms. If another Tooltip is opened within 400ms of one closing, it appears with no delay and no transition. This allows users to move the pointer along a toolbar and read each name in turn. If there is no TooltipProvider, every Tooltip waits 600ms, which is Base UI’s default. When the trigger receives keyboard focus, its Tooltip opens immediately.

A Tooltip closes when the pointer or focus moves away, when users press Escape, and when users click its trigger.

Position and SizeCopy Anchor Link

By default, a Tooltip opens above its trigger, centered on it. If it doesn’t fit there, Base UI moves it to another side. To change the position, set side, sideOffset, align, and alignOffset on TooltipContent.

The popup is as wide as its text, up to 320px, and longer text wraps.

ContentCopy Anchor Link

AccessibilityCopy Anchor Link

A Tooltip is visual only. Base UI sets no role on the popup, and no attribute connects the popup to the trigger, so screen readers announce the trigger’s own name and never the Tooltip.

RequirementsCopy Anchor Link

InstallationCopy Anchor Link

npx shadcn@latest add @summit/tooltip

UsageCopy Anchor Link

Render one TooltipProvider around the app so that all Tooltips share the 200ms delay.

import { Button } from '@/components/ui/button';
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
import { PlusIcon } from '@phosphor-icons/react';

<TooltipProvider>
    <Tooltip>
        <TooltipTrigger render={<Button variant="outline" size="icon" aria-label="Add client" />}>
            <PlusIcon />
        </TooltipTrigger>
        <TooltipContent>Add client</TooltipContent>
    </Tooltip>
</TooltipProvider>;

With a ShortcutCopy Anchor Link

To show a shortcut, place a Kbd or a KbdGroup after the text.

import { Kbd, KbdGroup } from '@/components/ui/kbd';

<Tooltip>
    <TooltipTrigger render={<Button variant="outline" />}>Print</TooltipTrigger>
    <TooltipContent>
        Print the invoice
        <KbdGroup>
            <Kbd>⌘</Kbd>
            <Kbd>P</Kbd>
        </KbdGroup>
    </TooltipContent>
</Tooltip>;

API ReferenceCopy Anchor Link

The parts accept the props of their matching parts in Base UI’s Tooltip, where TooltipContent is Tooltip.Popup. See the Base UI Tooltip documentation for closeDelay, timeout, disabled, and closeOnClick.

TooltipProviderCopy Anchor Link

TooltipContentCopy Anchor Link