Tooltip
FreeA short label that appears on hover or keyboard focus, to name a control or add a hint.
npx wunderui-cli add tooltipPlayground
Installation
npx wunderui-cli add tooltipWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
Tooltip,
TooltipContent,
TooltipProvider,
TooltipTrigger,
} from "@/components/ui/tooltip"Then use it:
import { Link2 } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"
export function CopyLink() {
return (
<Tooltip>
<TooltipTrigger describe={false} render={<IconButton variant="plain" aria-label="Copy link" />}>
<Link2 />
</TooltipTrigger>
<TooltipContent shortcut="⌘L">Copy link</TooltipContent>
</Tooltip>
)
}Expected result: A 36 px icon button. Hover it or focus it with Tab and a small dark tooltip with the text Copy link and a ⌘L chip appears above it.
When to use
Use Tooltip for
- The name of an icon button, with its shortcut
- The full text of a label that is cut off with an ellipsis
- A short hint on a control, or a confirmation that says what just happened
Use something else for
- Popover for content people read at length or act on: more than three lines, links, buttons or a form
- Hover Card for a preview of what a link points to, with an image or several lines of detail
- Alert for an error, a warning or a message the user must see without hovering
Placement
The tooltip sits on one side of the trigger, 8 px away, lined up with its start, centre or end. The arrow points at the middle of the trigger, and near a screen edge the tooltip flips sides.
Content
Use one short phrase without a full stop. A shortcut sits in its own chip after the label; long text wraps at 240 px (320 px for long translations), and more than three lines belongs in a Popover.
Appearance
The tooltip is always the dark surface with white text, in light or dark theme. The arrow can be switched off where the trigger is obvious.
Trigger
An icon button with no visible name needs a tooltip, and a truncated label carries its full text in one. A disabled button cannot take focus, so use a wrapper, and show the reason without hover too.
Add a title before publishing.
Timing
The docs site opens every tooltip at once. In your app, a TooltipProvider sets the delay, 600 ms by default, and moving to the next trigger within 300 ms shows its tooltip at once.
States
A tooltip stays closed until the trigger is hovered or focused. Hold it open or turn it off if needed; focus opens it without the delay, and Escape closes it.
Keyboard interactions
A tooltip has no controls of its own. It follows the focus of its trigger, so you reach it with the keys that reach the trigger.
- TaborShift+Tab
- Moves focus to the trigger. The tooltip opens as soon as the trigger receives keyboard focus, without the delay, and closes when focus leaves it.
- Escape
- Closes the open tooltip without moving focus. It opens again after the pointer or focus has left the trigger and returned.
A tooltip is never focusable itself. A trigger that can't take focus, such as a disabled button, needs a focusable wrapper for the keyboard to reach its tooltip.
Behavior and motion
What the tooltip does when it opens, where it goes, what it says and how it moves.
- Opening
- It opens when the pointer rests on the trigger for the delay, and at once on keyboard focus. It closes when pointer or focus leaves, on a press and on Escape, and touch has no hover.
- Delay
- By default the provider waits 600 ms and has a 300 ms timeout, so moving to the next trigger within it opens its tooltip at once. The docs site uses no delay, your app the default.
- Placement
- The tooltip sits on top by default, 8 px from the trigger. You choose the side and alignment, the arrow points at the trigger's middle, and near a viewport edge it flips and shifts back into view.
- Width
- The label grows to 240 px by default, or 320 px, then wraps and the surface grows taller. Padding is 16 px at the sides and 8 px above and below, 7 px when a shortcut chip is inside.
- Surface
- A dark surface with white text and a medium shadow, in light and dark theme alike. The corner is 8 px.
- Shortcut
- The shortcut is drawn in a dark chip after the label, 8 px away. The chip is a kbd element, so it is read as text.
- Confirmation
- The linger option opens the tooltip without the delay, and on close lets it drift up 4 px while it fades out slowly. Use it for a message that follows an action.
- Accessibility
- The surface has the tooltip role and an id. While it is open the trigger points at it with aria-describedby, unless you turn that off.
- Motion
- It opens with a quick fade and a zoom from 98 % after an 80 ms delay, so a passing pointer doesn't flash it, and closes faster. Within one group the animation is skipped.
- Reduced motion
- With reduced motion the zoom and drift are off and the tooltip only fades.
Anatomy
The trigger, the surface and what is on it. The figure holds the tooltip open on the right of its trigger so every part is visible, and the numbers name the parts below.
- data-slot="tooltip"
Holds the open state and links the trigger to the label. You can control it, switch it off or leave it uncontrolled, and it renders nothing itself.
- 1data-slot="tooltip-trigger"
The element the tooltip describes. It opens on hover and keyboard focus, and you pass your Button or IconButton and turn off the description if the tooltip repeats the trigger's name.
- 2data-slot="tooltip-content"
The dark surface, drawn in a portal above the trigger by default, 8 px away. Side, alignment and offset move it and it flips near a viewport edge, long text wraps at 240 or 320 px, Escape closes it.
- 3
The tooltip's text: one short phrase in 12 px medium, white.
- 4Optional
A key hint in its own dark chip after the label. Write it for the platform: ⌘K on macOS, Ctrl+K on Windows.
- 5Optional
The small point towards the trigger, which you can hide. It turns with the side the tooltip ends up on and keeps pointing at the middle of the trigger.
- Optional
Shares one delay between the tooltips below it, for example in a toolbar. The first opens after 600 ms, and moving to another trigger within 300 ms shows its tooltip at once.
Best practices
- Do
Give the trigger its own name with an aria-label, since a tooltip adds information and is never a control's only label. Turn off the description when it repeats that name.
- Do
Keep the text to one short phrase without a full stop. Longer text wraps at 240 px, or 320 px if allowed, and for more than three lines use a Popover.
- Do
Add a shortcut only if it works, and write it for the platform. Use the linger option for a confirmation like Copied to clipboard, which fades out slowly instead of snapping away.
- Do
Put a toolbar's tooltips in one TooltipProvider, so the delay is the same everywhere and moving along the buttons shows each tooltip at once.
- Do
Make the reason a control is disabled visible without hover, for example as helper text. The tooltip, on a wrapper that can take focus, then only repeats it.
- Do
Place the tooltip where it covers neither a neighbouring control nor the text of the row. Choose side and alignment for that, and let it flip near the edge.
- Don’t
Don't put links or buttons in a tooltip. It only opens on hover and focus of the trigger, so keyboard users can't reach them.
- Don’t
Don't make a tooltip the only place for an error, a confirmation or task-critical information. Touch and keyboard users may never see it.
- Don’t
Don't put a tooltip on text that isn't interactive. Nothing can take focus there, so a keyboard user never sees it.
API reference
One table per part. Every part also takes the props of the Base UI tooltip part it wraps and of the element it renders, such as id and aria-label.
Holds the open state and links the trigger to the label. You can control it, switch it off or leave it uncontrolled, and it renders nothing itself.
| Prop | Type | Default | Description |
|---|---|---|---|
| open | boolean | — | Controls whether the tooltip is open. Pair it with ; leave it out and the tooltip opens and closes on hover and focus by itself. |
| defaultOpen | boolean | false | Whether the tooltip is open on first render, when it is not controlled. |
| onOpenChange | (open, eventDetails) => void | — | Called when the tooltip should open or close, with the next value and the reason, such as the pointer, the focus or Escape. |
| disabled | boolean | false | Stops the tooltip from opening. The trigger keeps working as before. |
| trackCursorAxis | "none" | "x" | "y" | "both" | "none" | Makes the tooltip follow the pointer along an axis (, or ) instead of staying on the trigger. is the default. |
| actionsRef | RefObject<TooltipRoot.Actions | null> | — | A ref to imperative actions. - : Unmounts the tooltip popup. - : Closes the tooltip imperatively when called. |
| children | ReactNode | PayloadChildRenderFunction<Payload> | — | The content of the tooltip. This can be a regular React node or a render function that receives the of the active trigger. |
| defaultTriggerId | string | null | — | ID of the trigger that the tooltip is associated with. This is useful in conjunction with the prop to create an initially open tooltip. |
| disableHoverablePopup | boolean | false | Whether the tooltip contents can be hovered without closing the tooltip. |
| handle | TooltipHandle<Payload> | — | A handle to associate the tooltip with a trigger. If specified, allows external triggers to control the tooltip's open state. Can be created with the Tooltip.createHandle() method. |
| onOpenChangeComplete | (open) => void | — | Event handler called after any animations complete when the tooltip is opened or closed. |
| triggerId | string | null | — | ID of the trigger that the tooltip is associated with. This is useful in conjunction with the prop to create a controlled tooltip. There's no need to specify this prop when the tooltip is uncontrolled (that is, when the prop… |
Shares one delay between the tooltips below it, for example in a toolbar. The first opens after 600 ms, and moving to another trigger within 300 ms shows its tooltip at once.
| Prop | Type | Default | Description |
|---|---|---|---|
| delay | number | 600 | How long, in milliseconds, the pointer must rest on a trigger before its tooltip opens. The default is 600. Keyboard focus is not delayed. |
| closeDelay | number | 0 | How long, in milliseconds, the tooltip stays open after the pointer has left. The default is 0. |
| timeout | number | 300 | The time, in milliseconds, after one tooltip closes during which moving to another trigger in the group opens its tooltip at once. The default is 300. |
| children | ReactNode | — |
The element the tooltip describes. It opens on hover and keyboard focus, and you pass your Button or IconButton and turn off the description if the tooltip repeats the trigger's name.
| Prop | Type | Default | Description |
|---|---|---|---|
| render | ReactElement | (props, state) => ReactElement | — | Replaces the trigger's own element with your Button, IconButton or another element, which then gets the hover and focus behaviour and the . |
| describe | boolean | true | Whether the trigger points to the open tooltip with . Set when the tooltip only repeats the trigger's accessible name. The default is . |
| delay | number | 600 | Overrides the provider's delay for this trigger, in milliseconds. |
| closeDelay | number | 0 | Overrides the provider's close delay for this trigger, in milliseconds. |
| closeOnClick | boolean | true | Whether pressing the trigger closes the tooltip. The default is . |
| disabled | boolean | false | Stops this trigger from opening its tooltip. A natively disabled button cannot take focus; wrap it in an element with and make that the trigger. |
| handle | TooltipHandle<Payload> | — | A handle to associate the trigger with a tooltip. |
| payload | Payload | — | A payload to pass to the tooltip when it is opened. |
The dark surface, drawn in a portal above the trigger by default, 8 px away. Side, alignment and offset move it and it flips near a viewport edge, long text wraps at 240 or 320 px, Escape closes it.
| Prop | Type | Default | Description |
|---|---|---|---|
| side | "left" | "right" | "bottom" | "top" | "inline-end" | "inline-start" | "top" | The side of the trigger the tooltip sits on: (the default), , or . It flips to the opposite side when there is no room. |
| align | "center" | "end" | "start" | "center" | How the tooltip lines up with the trigger along the side: , (the default) or . The arrow keeps pointing at the middle of the trigger. |
| sideOffset | number | OffsetFunction | 8 | The distance between the trigger and the tooltip, in pixels. The default is 8. |
| arrow | boolean | true | Shows the small point towards the trigger. Set where the trigger is obvious. The default is . |
| shortcut | string | — | A key hint drawn in its own chip after the label, for example . Write it for the platform. |
| maxWidth | 240 | 320 | 240 | The widest the label grows before the text wraps onto the next line: 240 px (the default) or 320 px for long translations. |
| linger | boolean | false | For a confirmation such as : opens without the delay and, when it closes, drifts up slightly while it fades out slowly instead of snapping away. |
| anchor | Element | null | VirtualElement | RefObject<Element | null> | () => unknown | — | Positions the tooltip against another element or a virtual element instead of the trigger, for example the field a validation message belongs to. |
| render | ReactElement | (props, state) => ReactElement | — | Replaces the surface's element with another element or component. |
| className | string | (state) => string | undefined | — | Extra classes for the surface, merged after its own. A function receives the state and returns the classes. |
| style | CSSProperties | (state) => CSSProperties | undefined | — | Inline styles for the surface. A function receives the state and returns the styles. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("tooltip")npx wunderui-cli add tooltipThe full library index for assistants is at /llms.txt.