# Tooltip

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/tooltip
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=252-57

```tsx
import { Tooltip, TooltipProvider } from '@commenda/pathfinder/tooltip';
import { IconButton } from '@commenda/pathfinder/icon-button';
import { Download01Icon } from '@commenda/pathfinder/icons/Download01Icon';
<TooltipProvider>
  <Tooltip
    content="Download receipt"
    trigger={
      <IconButton label="Download receipt" tooltip={false}>
        <Download01Icon />
      </IconButton>
    }
  />
</TooltipProvider>;
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Styles are precompiled with Tailwind v4; consumers need no Tailwind scanning. Interactive callbacks belong in client components in Next.js App Router.

## Usage [#usage]

```tsx
import { Tooltip, TooltipProvider } from '@commenda/pathfinder/tooltip';
import { IconButton } from '@commenda/pathfinder/icon-button';
import { Download01Icon } from '@commenda/pathfinder/icons/Download01Icon';
<TooltipProvider>
  <Tooltip
    content="Download receipt"
    trigger={
      <IconButton label="Download receipt" tooltip={false}>
        <Download01Icon />
      </IconButton>
    }
  />
</TooltipProvider>;
```

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `trigger` | `ReactElement<any, string \| React.JSXElementConstructor<any>>` | required | Required; must forward its ref and event props |
| `content` | `string` | required | Required noninteractive text |
| `title` | `string` | optional | Optional title and shortcut chip |
| `shortcut` | `string` | optional | Optional title and shortcut chip |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-end" \| "inline-start"` | optional | top; collision-aware |
| `align` | `"start" \| "end" \| "center"` | optional | center |
| `showArrow` | `boolean` | optional | false |
| `sideOffset` | `number` | optional | 6; 11 with arrow |
| `disabled` | `boolean` | optional | Disables the tooltip, not its trigger |
| `open` | `boolean` | conditional | Controlled / uncontrolled visibility |
| `defaultOpen` | `boolean` | optional | Controlled / uncontrolled visibility |
| `onOpenChange` | `((open: boolean) => void)` | conditional | Required with open |
| `portalContainer` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null> \| null` | optional | Optional portal destination |

Mount TooltipProvider once per region for the 300 ms neighbor window. Hover opens after 100 ms; keyboard focus opens immediately. Escape closes it, and the pointer can move onto its content. Give the trigger its own accessible name. When wrapping IconButton, set tooltip={false} to avoid two hints. Use adjacent help for essential information and disabled reasons.

## Examples [#examples]

### Title [#title]


```tsx
<Tooltip
  title="Filing receipt"
  content="Download receipt"
  trigger={
    <IconButton label="Download receipt" tooltip={false}>
      <Download01Icon />
    </IconButton>
  }
/>;
```


### Shortcut [#shortcut]


```tsx
<Tooltip
  content="Download receipt"
  shortcut="⌘D"
  trigger={
    <IconButton label="Download receipt" tooltip={false}>
      <Download01Icon />
    </IconButton>
  }
/>;
```


### Placement [#placement]


```tsx
<>
  {(['top', 'bottom', 'left', 'right'] as const).map((side) => (
    <Tooltip
      key={side}
      side={side}
      showArrow
      content="Download receipt"
      trigger={
        <IconButton label="Download receipt" tooltip={false}>
          <Download01Icon />
        </IconButton>
      }
    />
  ))}
</>;
```


Read the [design guidance](/docs/components/tooltip#design-rules) before using these components.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Tooltip — 252:57 [#tooltip--25257]

- **TOOLTIP-01:** Supplemental, noninteractive text only. Essential instructions, errors, validation and required steps stay on the page. Links and buttons belong in Popover.
- **TOOLTIP-02:** Open after 100 ms hover, immediately on keyboard focus or for a neighboring tooltip within 300 ms. Use TooltipProvider around a region. Escape closes; the pointer can enter the popup without closing it. Open for as long as hover or focus remains.
- **TOOLTIP-03:** Icon-only controls need an accessible name that matches their tooltip. Do not repeat an already visible label. Field help uses a separate info control beside its label. Shortcut chips supplement another discoverable shortcut reference.
- **TOOLTIP-04:** Plain copy: sentence case, no period, ideally one line. Titles explain a metric or status. More than two lines belongs on the page. Pearl 1000, white Copy/12, 6 px radius, 8/12 px padding, menu elevation; 240 px maximum width, 320 with a title. Title/body gap 2; shortcut gap 8, chip height 16, pearl 900, radius 4. Arrow 10×5, off by default. Top placement flips as space requires; offsets 6 or 11 with arrow.