# Tooltip

> Short supporting text for unfamiliar controls.

- Type: Component (disclosure)
- Access: Free, open source
- Page: https://ui.xzero.co.uk/components/tooltip
- Markdown: https://ui.xzero.co.uk/components/tooltip/markdown
- Registry item: https://mcp.xzero.co.uk/r/tooltip.json
- Source file: `registry/components/tooltip/tooltip.tsx`
- Dependencies: @radix-ui/react-tooltip, motion
- Keywords: hint, overlay, react tooltip, radix tooltip, icon button tooltip, hover label, animated tooltip, tooltip component

## When to use

- One-line labels on icon-only buttons in toolbars.
- Revealing the full text of truncated labels on hover or focus.
- Dense toolbars where moving between icons should show labels instantly after the first one.

## When not to use

- Use popover for anything with links or controls inside.
- Use hover-card for rich previews such as a person or link.
- Avoid it for information people must see on touch devices, where hover does not exist.

## Installation

Register both Xzero UI namespaces in your project's components.json:

```json
{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}
```

```bash
npx shadcn@4.23.0 add @xzero-ui/tooltip
```

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

## Usage

```tsx
import { Tooltip } from "@/components/xzero/tooltip/tooltip";

export function ArchiveButton() {
  return (
    <Tooltip content="Archive">
      <button type="button" aria-label="Archive">
        <ArchiveIcon />
      </button>
    </Tooltip>
  );
}
```

## API reference

### Tooltip

A short label on hover or focus that opens without delay when moving between tooltips.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `content` (required) | `ReactNode` | – | Tooltip content. Strings and numbers crossfade and resize when they change while open. |
| `children` (required) | `ReactElement` | – | The trigger. Rendered with asChild, so it must accept a ref and be focusable. |
| `side` | `"top" \| "bottom"` | `"top"` | Preferred side of the trigger. |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focusing the trigger opens the tooltip. |
| Escape | Closes the tooltip. |

## Accessibility

- Radix links the content to the trigger with aria-describedby and renders role="tooltip".
- Content is supplemental: icon-only triggers still need their own aria-label.
- Do not put interactive elements inside; use popover instead.

## Motion

- Opens after 250ms with a 3px rise from 0.97 scale; within 300ms of another tooltip it opens instantly with a fade only.
- Changing string content rises in with a blur while the bubble springs to the new size.
- Reduced motion removes the transform and keeps a 90ms opacity fade.

## Responsive behavior

- The bubble caps at 15rem and wraps longer text; Radix flips it to the other side near viewport edges.
- It opens on hover and keyboard focus, so touch users rarely see it; never hide essential information in one.

## Performance

- Each tooltip brings its own provider and mounts content in a portal only while open.
- A ResizeObserver measures the text only to spring the bubble size when content changes while open.

## Notes for AI

- Use for one-line labels on icon buttons and truncated text. Use hover-card for rich previews and popover for anything interactive.
- Each Tooltip brings its own provider; no app-level wrapper is needed.

## Related

- [Popover](https://ui.xzero.co.uk/components/popover/markdown): A small anchored surface for contextual information.
- [Hover card](https://ui.xzero.co.uk/components/hover-card/markdown): Preview a person or link on hover or focus without leaving the page.
- [Action button](https://ui.xzero.co.uk/components/action-button/markdown): A compact button for frequent toolbar actions.

## Also in overlays

- [Dialog](https://ui.xzero.co.uk/components/dialog/markdown): A focused surface for decisions that need attention.
- [Drawer](https://ui.xzero.co.uk/components/drawer/markdown): A temporary side surface for focused work.
- [Bottom sheet](https://ui.xzero.co.uk/components/bottom-sheet/markdown): A sheet that rests at a peek or full height and follows your finger.
- [Share access](https://ui.xzero.co.uk/components/share-access/markdown): A share panel: invite people as validated email chips with suggestions, change roles from a compact menu, remove with undo, switch link access and copy the link, with every change landing in place.
- [Confirm popover](https://ui.xzero.co.uk/components/confirm-popover/markdown): A destructive button that grows into a small confirmation card, with the consequence, optional type-to-confirm, progress on the Confirm button, and a check or error before folding back.

## Guidance for AI tools

Tooltip: Short supporting text for unfamiliar controls. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt