# Tooltip

## Overview

A small floating label that appears on hover (or focus) over a trigger element, providing a short contextual explanation — typically for icon-only buttons, abbreviated text, or any element where the visual label alone isn't sufficient.

---

## When to Use

- Icon-only buttons that need a text label for clarity
- Abbreviated data that should show the full value on hover
- Action buttons where the intent isn't immediately obvious

## When NOT to Use

- Rich previews with images or complex content — use `<HoverCard>` instead.
- Persistent contextual information — use `<Popover>` or inline text instead.
- Critical information the user must read — Tooltips are hidden by default; don't put required content there.

---

## Anatomy

```
<TooltipProvider>           ← Provided by XerticaProvider
  <Tooltip>
    <TooltipTrigger asChild>
      <Button />
    </TooltipTrigger>
    <TooltipContent>
      Descriptive label
    </TooltipContent>
  </Tooltip>
</TooltipProvider>
```

> `<TooltipProvider>` is automatically included in `<XerticaProvider>`. You do not need to wrap it manually.

---

## Props

### Tooltip

| Prop            | Type                      | Default | Description           |
| --------------- | ------------------------- | ------- | --------------------- |
| `open`          | `boolean`                 | —       | Controlled open state |
| `defaultOpen`   | `boolean`                 | `false` | Uncontrolled default  |
| `onOpenChange`  | `(open: boolean) => void` | —       | State handler         |
| `delayDuration` | `number`                  | `700`   | Hover delay in ms     |

### TooltipTrigger

| Prop      | Type      | Description              |
| --------- | --------- | ------------------------ |
| `asChild` | `boolean` | Renders as child element |

### TooltipContent

| Prop         | Type                                     | Default | Description           |
| ------------ | ---------------------------------------- | ------- | --------------------- |
| `side`       | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Positioning side      |
| `sideOffset` | `number`                                 | `4`     | Distance from trigger |
| `className`  | `string`                                 | —       | Additional classes    |

---

## Examples

### Icon Button with Tooltip

```tsx
import { Tooltip, TooltipContent, TooltipTrigger, Button } from 'xertica-ui/ui';
import { Settings } from 'lucide-react';

<Tooltip>
  <TooltipTrigger asChild>
    <Button variant="ghost" size="icon" aria-label="Settings">
      <Settings className="size-4" />
    </Button>
  </TooltipTrigger>
  <TooltipContent>
    <p>Settings</p>
  </TooltipContent>
</Tooltip>;
```

### Truncated Text Preview

```tsx
<Tooltip>
  <TooltipTrigger asChild>
    <span className="truncate max-w-[150px] block">{longTitle}</span>
  </TooltipTrigger>
  <TooltipContent>
    <p>{longTitle}</p>
  </TooltipContent>
</Tooltip>
```

---

## AI Rules

- `TooltipProvider` is **not needed** — it's injected by `<XerticaProvider>`. Do not add it manually unless outside provider scope.
- Always use `<TooltipTrigger asChild>` when wrapping a `<Button>` — without `asChild` the DOM renders a button inside a button.
- Tooltip content should be a **short phrase** (2–4 words) — not long descriptions or instructions.
- Add `aria-label` to icon-only trigger buttons as well — tooltips don't replace semantic accessibility.

---

## Related Components

- [`HoverCard`](./hover-card.md) — For rich preview content on hover
- [`Popover`](./popover.md) — For persistent floating content panels