# Tooltip

> A short text label that appears on hover and keyboard focus.

Category: Overlays · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/tooltip

Tooltips name icon-only controls and add brief, non-essential hints. They appear after a short delay on hover and immediately on keyboard focus, stay open while hovered, and close on Escape. Tooltip text must not be the only place important information lives, and it cannot contain links or buttons; use Popover or HoverCard for interactive content.

## Import

```tsx
import { Tooltip, TooltipProvider } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { Button, Icon, Tooltip } from '@bindshq/stance-react';

export function Basic() {
  return (
    <Tooltip content="Copy signature HTML">
      <Button variant="outline" size="sm" aria-label="Copy signature HTML">
        <Icon name="copy" />
      </Button>
    </Tooltip>
  );
}
```

### Placement

```tsx
import { Button, Tooltip } from '@bindshq/stance-react';

export function Placement() {
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
      {(['top', 'right', 'bottom', 'left'] as const).map((side) => (
        <Tooltip key={side} content={`Shown on the ${side}`} side={side}>
          <Button variant="secondary" size="sm">
            {side}
          </Button>
        </Tooltip>
      ))}
    </div>
  );
}
```

### Shared delay

Inside a TooltipProvider, moving between tooltips skips the delay.

```tsx
import { Button, Icon, Tooltip, TooltipProvider } from '@bindshq/stance-react';

export function SharedDelay() {
  const tools = [
    { icon: 'pencil', label: 'Edit' },
    { icon: 'copy', label: 'Duplicate' },
    { icon: 'download', label: 'Download' },
    { icon: 'trash', label: 'Delete' },
  ] as const;
  return (
    <TooltipProvider delay={400}>
      <div style={{ display: 'flex', gap: 4 }}>
        {tools.map((t) => (
          <Tooltip key={t.label} content={t.label}>
            <Button variant="ghost" size="sm" aria-label={t.label}>
              <Icon name={t.icon} />
            </Button>
          </Tooltip>
        ))}
      </div>
    </TooltipProvider>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Tooltip | `content` (required) | `ReactNode` | None | Tooltip text. Keep it under ~80 characters. |
| Tooltip | `children` (required) | `ReactElement` | None | A single focusable element. Wrap disabled buttons in a focusable span if they need a tooltip. |
| Tooltip | `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Preferred side; flips near edges. |
| Tooltip | `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment along the side. |
| Tooltip | `sideOffset` | `number` | `6` | Gap from the trigger in px. |
| Tooltip | `delay` | `number` | `500` | Hover delay in ms (falls back to the provider). |
| Tooltip | `closeDelay` | `number` | `100` | Grace period so the pointer can move onto the tooltip. |
| Tooltip | `open / defaultOpen / onOpenChange` | `boolean / boolean / (open: boolean) => void` | None | Controlled or uncontrolled state. |
| Tooltip | `disabled` | `boolean` | `false` | Never show the tooltip. |
| Tooltip | `className` | `string` | None | Class for the tooltip bubble. |
| TooltipProvider | `delay` | `number` | `500` | Default hover delay for descendants. |
| TooltipProvider | `skipDelay` | `number` | `300` | Window after a tooltip closes in which the next opens instantly. |

## Accessibility

- The bubble has role="tooltip" and is referenced from the trigger with aria-describedby while visible (existing descriptions are preserved).
- Opens on keyboard focus without a delay; opening by click focus is suppressed to avoid flicker.
- Hoverable and dismissible without moving the pointer, meeting WCAG 1.4.13 Content on Hover or Focus.
- Touch input never opens tooltips; do not rely on them for essential information.

## Keyboard

| Keys | Action |
| --- | --- |
| `Tab` | Focusing the trigger shows the tooltip. |
| `Esc` | Hides the tooltip. |

## Guidelines

**Do**

- Use to name icon-only buttons (in addition to their aria-label).
- Keep text short and sentence-case.

**Don’t**

- Put links, buttons or form fields in a tooltip.
- Repeat the visible label of the trigger.

## Related

- https://stanceui.com/components/hover-card
- https://stanceui.com/components/popover
- https://stanceui.com/components/icon-button