# Tooltip

```tsx
import { Tooltip } from '@tangible/ui';
```

Interactive docs and examples: [Tooltip in Storybook](https://storybook-tangible-ui.pages.dev/?path=/docs/overlays-tooltip--docs).

## Tooltip props

| Prop | Type | Default | Description |
| - | - | - | - |
| `children` | `React.ReactNode` | | |
| `defaultOpen?` | `boolean` | `false` | Default open state for uncontrolled usage. |
| `delayDuration?` | `number` | | Override provider's delay for this tooltip. |
| `onOpenChange?` | `(open: boolean) => void` | | Callback when open state changes. |
| `open?` | `boolean` | | Controlled open state. |

### Tooltip.Provider

Also exported as `TooltipProvider`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `children` | `React.ReactNode` | | |
| `closeDelayDuration?` | `number` | `150` | Delay in ms before tooltip closes after pointer leaves. Provides a brief window for users to move their pointer to the tooltip content (partial WCAG 1.4.13 compliance). |
| `delayDuration?` | `number` | `400` | Delay in ms before tooltip opens on hover. |
| `skipDelayDuration?` | `number` | `300` | Warmth window in ms. Tooltips under one provider form a group: while one is showing, or for this long after it closes, the next opens at once instead of waiting out `delayDuration`. Gliding along a toolbar, each tooltip appears immediately, one at a time. Escape cools the group: a dismissed tooltip doesn't warm the next. Toolbar provides a group automatically. |

### Tooltip.Trigger

Also exported as `TooltipTrigger`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `children` | `React.ReactNode` | | |
| `aria-label?` | `string` | | Accessible label for the non-asChild wrapper span. When `asChild` is false, the trigger renders as a `<span>` with no semantic role — this label gives assistive technology a name for the focusable element. Omitting this when the span wraps non-descriptive content (e.g. an icon) means screen readers will announce the element with no accessible name. |
| `asChild?` | `boolean` | `false` | When true, merges props onto the child element instead of wrapping in a span. Child must be a single React element that accepts ref and event handlers. |

### Tooltip.Content

Also exported as `TooltipContent`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `children` | `React.ReactNode` | | |
| `align?` | `"center" \| "end" \| "start"` | `'center'` | Alignment along the side. |
| `className?` | `string` | | Additional CSS class names. |
| `side?` | `"bottom" \| "left" \| "right" \| "top"` | `'top'` | Preferred side of the trigger to place the tooltip. |
| `sideOffset?` | `number` | `8` | Distance from the trigger in pixels. |
| `theme?` | `"dark" \| "light"` | `'dark'` | Visual theme variant. |

## Examples

- [Toolbar warm-up](https://storybook-tangible-ui.pages.dev/?path=/story/overlays-tooltip--toolbar-warm-up): Inside a `Toolbar`, tooltips share a warmth group with no setup. The first
  waits its delay; glide on to the next and each appears at once, one at a
  time. After a pause (`skipDelayDuration`, 300ms) or an Escape, the next waits
  again. A `TooltipProvider` gives any other set of tooltips the same.

Other stories: Basic, Placement, Alignment, With asChild, Disabled Trigger, With IconButton, IconButton showTooltip, Custom Delay, With Provider, Long Content, Toolbar Pattern, Light Variant, Static (Inspect) ([interactive page](https://storybook-tangible-ui.pages.dev/?path=/docs/overlays-tooltip--docs)).

## Component API tokens

Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.

- `--tui-tooltip-bg`
- `--tui-tooltip-fg`
- `--tui-tooltip-radius`
- `--tui-tooltip-z`

---

Interactive version: https://storybook-tangible-ui.pages.dev/?path=/docs/overlays-tooltip--docs