# Tooltip

Headless, unstyled floating label that opens on hover after a delay or on keyboard focus, and closes on leave, blur or `Escape`. It never takes focus and holds no interactive content.

## Use for

- a label for an icon-only button
- the full text of truncated content
- a short hint shown on hover or focus
- a toolbar whose tooltips switch instantly as the pointer moves

## Practices

- Do: Wrap a cluster of triggers, such as a toolbar, in `Tooltip.Group` so moving between them switches at once.
- Do: Pass the trigger’s own button through `render` instead of nesting a button inside `Tooltip.Trigger`.
- Do: Animate the popup with `data-starting-style` and `data-ending-style`.
- Don't: Put links or buttons in the popup. It cannot be reached by keyboard. Use `Popover` instead.
- Don't: Use the tooltip as a button’s only name. Give the trigger its own `aria-label`; the tooltip only describes it.
- Don't: Pass `id` to `Tooltip.Positioner`. The primitive owns it to pair the trigger’s `aria-describedby`.

## API reference

### Tooltip.Root

Holds the open state, position and hover delays. Renders no element. Nested tooltips are supported.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` |  | Whether the tooltip is open, when controlled. |
| `defaultOpen` | `boolean` | `false` | Whether the tooltip is open on mount, when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` |  | Called with the new open state. |
| `placement` | `Placement` | `'top'` | Where the tooltip sits relative to the trigger. |
| `sideOffset` | `number` | `4` | Gap to the trigger in px. |
| `delay` | `number` | `200` | Hover open delay in ms. Ignored inside a `Tooltip.Group`. |
| `closeDelay` | `number` | `0` | Hover close delay in ms. Ignored inside a `Tooltip.Group`. |

### Tooltip.Group

Shares one delay across the tooltips inside it. Renders no element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `delay` | `number \| { open?: number; close?: number }` | `{ open: 200, close: 100 }` | Open and close delay in ms. Replaces each member’s own. |
| `timeoutMs` | `number` | `300` | How long after a tooltip closes the next one still opens instantly, in ms. |

### Tooltip.Trigger

A `button` with `aria-describedby` pointing at the tooltip. Carries `data-open` or `data-closed`.

### Tooltip.Portal

Portals its children while the tooltip is mounted.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `root` | `HTMLElement \| null \| RefObject<HTMLElement \| null>` | ``the `Portal` container`` | The element to portal into. |

### Tooltip.Positioner

The floating `div` with `role="tooltip"`, rendered only while mounted. Carries `data-side` and the anchor CSS variables.

### Tooltip.Popup

The visible `div`. Carries `data-open`, `data-closed`, `data-starting-style` and `data-ending-style`.

### Tooltip.Arrow

An optional `FloatingArrow` `svg` pointing at the trigger. Carries `data-side`.

## Examples

### Icon button tooltip

```tsx
<Tooltip.Root>
  <Tooltip.Trigger render={<IconButton aria-label='Settings' />} />
  <Tooltip.Portal>
    <Tooltip.Positioner>
      <Tooltip.Popup>
        Settings
        <Tooltip.Arrow />
      </Tooltip.Popup>
    </Tooltip.Positioner>
  </Tooltip.Portal>
</Tooltip.Root>
```

## Related

- [Popover](/docs/components/popover.md)
- [Portal](/docs/primitives/portal.md)
