# Tooltip

A short label that shows on hover or focus of its trigger, and closes on Escape. Styled over the headless `Tooltip` primitive; the popup portals and positions itself.

## Use for

- a label for an icon-only control
- a short hint on hover or focus
- a row of toolbar tooltips that open at once after the first

## Practices

- Do: Wrap a toolbar of tooltips in `Tooltip.Group`, so moving between triggers opens the next at once.
- Do: Pass `render` to `Tooltip.Trigger` to make an existing `Button` the trigger.
- Don't: Put interactive content in `Tooltip.Popup`. Use a popover or menu instead.
- Don't: Rely on a tooltip as the only accessible name of an icon-only button. Give the button its own name with `VisuallyHidden` or `aria-label`.

## API reference

### Tooltip.Root

Holds the open state and positioning. Renders no element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` |  | Open state, when controlled. |
| `defaultOpen` | `boolean` | `false` | Open state on mount, when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` |  | Called with the new open state. |
| `placement` | `'top' \| 'right' \| 'bottom' \| 'left' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'bottom-start' \| 'bottom-end' \| 'left-start' \| 'left-end'` | `'top'` | Preferred side and alignment. Flips and shifts to stay in view. |
| `sideOffset` | `number` | `4` | Gap in px between trigger and popup. |
| `delay` | `number` | `200` | Ms before opening on hover. Ignored inside `Tooltip.Group`. |
| `closeDelay` | `number` | `0` | Ms before closing on hover out. Ignored inside `Tooltip.Group`. |

### Tooltip.Group

Shares one delay across the tooltips inside, so once one opens the next opens at once.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `delay` | `number \| { open?: number; close?: number }` | `{ open: 200, close: 100 }` | Replaces each member's `delay` and `closeDelay`. |
| `timeoutMs` | `number` | `300` | Ms after the last close before the group waits for the delay again. |

### Tooltip.Trigger

A `button` (`type='button'`) wired to open the tooltip and described by it. Carries `data-open` or `data-closed`.

Slot: `cl-tooltip-trigger`

### Tooltip.Popup

The label, as `role="tooltip"`. Portals, and sits in a positioner (`cl-tooltip-positioner`) with `data-side`. Mounts only while open.

Slot: `cl-tooltip-popup`

## Examples

### An icon button with a tooltip

```tsx
<Tooltip.Root>
  <Tooltip.Trigger render={<Button variant='ghost' shape='square' />}>
    <Icon glyph={Copy} />
    <VisuallyHidden>Copy</VisuallyHidden>
  </Tooltip.Trigger>
  <Tooltip.Popup>Copy</Tooltip.Popup>
</Tooltip.Root>
```

## Related

- [VisuallyHidden](/docs/components/visually-hidden.md)
- [Button](/docs/components/button.md)
