# Tooltip

A short label shown on hover, in any of 4 directions.

- Category: Core Elements
- Page: https://wunderui.com/components/tooltip
- Tier: Free

## Install

```bash
npx wunderui-cli add tooltip
```

## Import

```tsx
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip"
```

## Minimal usage

Then use it:

```tsx
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.

## Usage

```tsx
import { Link2 } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export function Example() {
  return (
    <Tooltip>
      <TooltipTrigger describe={false} render={<IconButton variant="plain" aria-label="Copy link" />}>
        <Link2 />
      </TooltipTrigger>
      <TooltipContent>Copy link</TooltipContent>
    </Tooltip>
  )
}
```

## 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

- [Popover](https://wunderui.com/components/popover) for content people read at length or act on: more than three lines, links, buttons or a form
- [Hover Card](https://wunderui.com/components/hover-card) for a preview of what a link points to, with an image or several lines of detail
- [Alert](https://wunderui.com/components/alert) for an error, a warning or a message the user must see without hovering

## Keyboard

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.

| Key | Action |
|---|---|
| `Tab` or `Shift+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

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

- `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.
- `TooltipProvider`: 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.
- `TooltipTrigger`: 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.
- `TooltipContent`: 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.
- `Label`: The tooltip's text: one short phrase in 12 px medium, white.
- `Shortcut`: A key hint in its own dark chip after the label. Write it for the platform: ⌘K on macOS, Ctrl+K on Windows.
- `Arrow`: 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.

## Best practices

### When to use

- Use it for a short hint on a control: the name of an icon button, a shortcut, a truncated text in full. For content people read at length or act on, use a Popover.

### 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.
- 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.
- 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.
- 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.
- 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.
- 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 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 put a tooltip on text that isn't interactive. Nothing can take focus there, so a keyboard user never sees it.

## API reference

### Tooltip

| Prop | Type | Default | Description |
|---|---|---|---|
| actionsRef | React.RefObject<TooltipRoot.Actions \| null> |  | A ref to imperative actions. - `unmount`: Unmounts the tooltip popup. - `close`: Closes the tooltip imperatively when called. |
| children | React.ReactNode \| PayloadChildRenderFunction<Payload> |  | The content of the tooltip. This can be a regular React node or a render function that receives the `payload` of the active trigger. |
| defaultOpen | boolean | false | Whether the tooltip is open on first render, when it is not controlled. |
| defaultTriggerId | string \| null |  | ID of the trigger that the tooltip is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open tooltip. |
| disabled | boolean | false | Stops the tooltip from opening. The trigger keeps working as before. |
| 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. |
| onOpenChange | ((open: boolean, eventDetails: TooltipRoot.ChangeEventDetails) => void) |  | Called when the tooltip should open or close, with the next value and the reason, such as the pointer, the focus or Escape. |
| onOpenChangeComplete | ((open: boolean) => void) |  | Event handler called after any animations complete when the tooltip is opened or closed. |
| open | boolean |  | Controls whether the tooltip is open. Pair it with `onOpenChange`; leave it out and the tooltip opens and closes on hover and focus by itself. |
| trackCursorAxis | 'none' \| 'x' \| 'y' \| 'both' | 'none' | Makes the tooltip follow the pointer along an axis (`x`, `y` or `both`) instead of staying on the trigger. `none` is the default. |
| triggerId | string \| null |  | ID of the trigger that the tooltip is associated with. This is useful in conjunction with the `open` prop to create a controlled tooltip. There's no need to specify this prop when the tooltip is uncontrolled (that is, when the `open` prop… |

### TooltipContent

| Prop | Type | Default | Description |
|---|---|---|---|
| align | "center" \| "end" \| "start" | 'center' | How the tooltip lines up with the trigger along the side: `start`, `center` (the default) or `end`. The arrow keeps pointing at the middle of the trigger. |
| anchor | Element \| null \| VirtualElement \| React.RefObject<Element \| null> \| (() => Element \| VirtualElement \| null) |  | Positions the tooltip against another element or a virtual element instead of the trigger, for example the field a validation message belongs to. |
| arrow | boolean | true | Shows the small point towards the trigger. Set `false` where the trigger is obvious. The default is `true`. |
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the surface, merged after its own. A function receives the state and returns the classes. |
| linger | boolean | false | For a confirmation such as `Copied to clipboard`: opens without the delay and, when it closes, drifts up slightly while it fades out slowly instead of snapping away. |
| 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. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the surface's element with another element or component. |
| shortcut | string |  | A key hint drawn in its own chip after the label, for example `⌘K`. Write it for the platform. |
| side | "left" \| "right" \| "bottom" \| "top" \| "inline-end" \| "inline-start" | "top" | The side of the trigger the tooltip sits on: `top` (the default), `right`, `bottom` or `left`. It flips to the opposite side when there is no room. |
| sideOffset | number \| OffsetFunction | 8 | The distance between the trigger and the tooltip, in pixels. The default is 8. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline styles for the surface. A function receives the state and returns the styles. |

Also accepts React.HTMLAttributes attributes.

### TooltipProvider

| Prop | Type | Default | Description |
|---|---|---|---|
| children | React.ReactNode |  |  |
| closeDelay | number | 0 | How long, in milliseconds, the tooltip stays open after the pointer has left. The default is 0. |
| 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. |
| 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. |

### TooltipTrigger

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| 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 `true`. |
| delay | number | 600 | Overrides the provider's delay for this trigger, in milliseconds. |
| describe | boolean | true | Whether the trigger points to the open tooltip with `aria-describedby`. Set `false` when the tooltip only repeats the trigger's accessible name. The default is `true`. |
| disabled | boolean | false | Stops this trigger from opening its tooltip. A natively disabled button cannot take focus; wrap it in an element with `tabIndex={0}` 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. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the trigger's own element with your Button, IconButton or another element, which then gets the hover and focus behaviour and the `aria-describedby`. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.ButtonHTMLAttributes attributes.

## Examples

### Placement: the side of the trigger and how the tooltip lines up with it

```tsx
import { Link2 } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export function Example() {
  return (
    <Tooltip>
      <TooltipTrigger describe={false} render={<IconButton variant="plain" aria-label="Copy link" />}>
        <Link2 />
      </TooltipTrigger>
      <TooltipContent side="top" align="center">Copy link</TooltipContent>
    </Tooltip>
  )
}
```

### Content: a label, a shortcut, and text that wraps at 240 or 320 px

```tsx
import { Link2 } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export function Example() {
  return (
    <Tooltip>
      <TooltipTrigger describe={false} render={<IconButton variant="plain" aria-label="Copy link" />}>
        <Link2 />
      </TooltipTrigger>
      <TooltipContent>Copy link</TooltipContent>
    </Tooltip>
  )
}
```

### Appearance: the dark surface with or without the arrow

```tsx
import { Link2 } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export function Example() {
  return (
    <Tooltip>
      <TooltipTrigger describe={false} render={<IconButton variant="plain" aria-label="Copy link" />}>
        <Link2 />
      </TooltipTrigger>
      <TooltipContent>Copy link</TooltipContent>
    </Tooltip>
  )
}
```

### Trigger: an icon button, a truncated label and a disabled button

```tsx
import { Link2 } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export function Example() {
  return (
    <Tooltip>
      <TooltipTrigger describe={false} render={<IconButton variant="plain" aria-label="Copy link" />}>
        <Link2 />
      </TooltipTrigger>
      <TooltipContent>Copy link</TooltipContent>
    </Tooltip>
  )
}
```

### Timing: no delay, the library delay, a group and a confirmation

```tsx
import { Link2 } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip"

export function Example() {
  return (
    <TooltipProvider delay={0}>
      <Tooltip>
        <TooltipTrigger describe={false} render={<IconButton variant="plain" aria-label="Copy link" />}>
          <Link2 />
        </TooltipTrigger>
        <TooltipContent>Copy link</TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}
```

### States: hover and focus, held open and disabled

```tsx
import { Link2 } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export function Example() {
  return (
    <Tooltip>
      <TooltipTrigger describe={false} render={<IconButton variant="plain" aria-label="Copy link" />}>
        <Link2 />
      </TooltipTrigger>
      <TooltipContent>Copy link</TooltipContent>
    </Tooltip>
  )
}
```

## In context

### Editor toolbar: one delay for every button

The first tooltip opens after the delay; moving to the next button within 300 ms shows its tooltip at once. Keyboard focus shows it without delay.

```tsx
import { AlignCenter, AlignLeft, Bold, Italic, Underline } from "lucide-react"
import { Toolbar, ToolbarButton, ToolbarSeparator } from "@/components/ui/toolbar"
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip"

export function Example() {
  return (
    <TooltipProvider delay={600} timeout={300}>
      <Toolbar aria-label="Formatting">
        <Tooltip>
          <TooltipTrigger describe={false} render={<ToolbarButton aria-label="Bold" />}>
            <Bold />
          </TooltipTrigger>
          <TooltipContent side="bottom" shortcut="⌘B">
            Bold
          </TooltipContent>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger describe={false} render={<ToolbarButton aria-label="Italic" />}>
            <Italic />
          </TooltipTrigger>
          <TooltipContent side="bottom" shortcut="⌘I">
            Italic
          </TooltipContent>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger describe={false} render={<ToolbarButton aria-label="Underline" />}>
            <Underline />
          </TooltipTrigger>
          <TooltipContent side="bottom" shortcut="⌘U">
            Underline
          </TooltipContent>
        </Tooltip>
        <ToolbarSeparator />
        <Tooltip>
          <TooltipTrigger describe={false} render={<ToolbarButton aria-label="Align left" />}>
            <AlignLeft />
          </TooltipTrigger>
          <TooltipContent side="bottom">Align left</TooltipContent>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger describe={false} render={<ToolbarButton aria-label="Align center" />}>
            <AlignCenter />
          </TooltipTrigger>
          <TooltipContent side="bottom">Align center</TooltipContent>
        </Tooltip>
      </Toolbar>
    </TooltipProvider>
  )
}
```

### Icon buttons in a list: each action names itself

Row actions are icon buttons without a visible label, so each needs a tooltip. The tooltip sits where it covers neither a neighbouring action nor the row text.

```tsx
import { Pencil, Trash2 } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

const PROJECTS = ["Atlas redesign", "Billing migration", "Onboarding flow"]

export function Example() {
  return (
    <div className="w-96 max-w-full">
      <h3 className="mb-3 text-base font-semibold text-foreground">Projects</h3>
      <ul className="divide-y divide-border rounded-xl border border-border bg-card px-4 text-sm">
        {PROJECTS.map((name) => (
          <li key={name} className="flex items-center justify-between py-2">
            <span className="text-foreground">{name}</span>
            <span className="flex items-center gap-1">
              <Tooltip>
                <TooltipTrigger describe={false} render={<IconButton variant="ghost" size="sm" aria-label={`Edit ${name}`} />}>
                  <Pencil />
                </TooltipTrigger>
                <TooltipContent align="end">Edit project</TooltipContent>
              </Tooltip>
              <Tooltip>
                <TooltipTrigger describe={false} render={<IconButton variant="ghost" size="sm" aria-label={`Delete ${name}`} />}>
                  <Trash2 />
                </TooltipTrigger>
                <TooltipContent align="end">Delete project</TooltipContent>
              </Tooltip>
            </span>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

### Truncated names in a list: the tooltip shows the full name

A long file name ends in an ellipsis and the tooltip shows it in full. The full name is also available in the detail view.

```tsx
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

const FILES = [
  { name: "Brand-guidelines-2026-v7-approved-by-legal.pdf", size: "6.1 MB" },
  { name: "Q3-board-review-final-version-2026.pdf", size: "2.4 MB" },
  { name: "Roadmap-H2.pdf", size: "820 KB" },
]

export function Example() {
  return (
    <div className="w-96 max-w-full">
      <h3 className="mb-3 text-base font-semibold text-foreground">Files</h3>
      <ul className="divide-y divide-border rounded-xl border border-border bg-card px-4 text-sm">
        {FILES.map(({ name, size }) => (
          <li key={name} className="flex items-center justify-between gap-4 py-3">
            <Tooltip>
              <TooltipTrigger
                describe={false}
                render={<button type="button" className="focus-ring min-w-0 flex-1 truncate rounded-sm text-left text-foreground outline-none" />}
              >
                {name}
              </TooltipTrigger>
              <TooltipContent align="start">{name}</TooltipContent>
            </Tooltip>
            <span className="shrink-0 text-text-secondary">{size}</span>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

### Disabled action with a visible reason

The card says why Publish is unavailable in plain text. The tooltip on the disabled button repeats it.

```tsx
import { Button } from "@/components/ui/button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export function Example() {
  return (
    <div className="w-96 max-w-full rounded-xl border border-border bg-card p-4">
      <p className="text-sm text-text-secondary">Add a title before publishing.</p>
      <div className="mt-4 flex justify-end gap-2">
        <Button variant="plain">Cancel</Button>
        <Tooltip>
          <TooltipTrigger render={<span tabIndex={0} className="inline-flex" />}>
            <Button variant="gradient" disabled>
              Publish
            </Button>
          </TooltipTrigger>
          <TooltipContent align="end">Add a title before publishing</TooltipContent>
        </Tooltip>
      </div>
    </div>
  )
}
```

## For AI agents

`get_component("tooltip")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
