npm package: @polarityio/pi-tooltip
Description: Tooltip component with Floating UI positioning, configurable triggers, delays, and arrow
Latest version: 1.0.3

# Polarity Integration Component Library

## Tooltip Component

A tooltip overlay positioned with Floating UI that supports configurable placement, multiple trigger modes, delays, and an optional arrow.

## Installation

```bash
npm install @polarityio/pi-tooltip
```

### Peer Dependencies

- [lit](https://lit.dev/) ^3.0.0

## Usage

```javascript
import '@polarityio/pi-tooltip';
```

### Basic Tooltip (hover + focus)

```html
<button>
  Hover me
  <pi-tooltip>This is a tooltip</pi-tooltip>
</button>
```

### Custom Placement

```html
<button>
  Right tooltip
  <pi-tooltip placement="right">Appears on the right</pi-tooltip>
</button>
```

### Click Trigger

```html
<button>
  Click me
  <pi-tooltip trigger="click">Shown on click</pi-tooltip>
</button>
```

### With Delay and No Arrow

```javascript
html`
  <button>
    Delayed tooltip
    <pi-tooltip open-delay="500" close-delay="200" ?arrow=${false}>
      Appears after 500ms
    </pi-tooltip>
  </button>
`;
```

### Targeting an External Element

```html
<span id="my-target">Hover this text</span>
<pi-tooltip for="my-target" placement="bottom">
  Tooltip for the span above
</pi-tooltip>
```

## API Reference

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `placement` | `Placement` | `'top'` | Where the tooltip appears relative to the target. Reflected to attribute. |
| `open` | `boolean` | `false` | Forces the tooltip to be visible. Reflected to attribute. |
| `disabled` | `boolean` | `false` | Disables the tooltip. Reflected to attribute. |
| `delay` | `number` | `0` | Default delay in milliseconds for both opening and closing. |
| `openDelay` | `number \| undefined` | `undefined` | Delay before opening in milliseconds. Overrides `delay`. Set via `open-delay` attribute. |
| `closeDelay` | `number \| undefined` | `undefined` | Delay before closing in milliseconds. Overrides `delay`. Set via `close-delay` attribute. |
| `offset` | `number` | `8` | Distance in pixels between the tooltip and its target. |
| `arrow` | `boolean` | `true` | Whether to show an arrow pointing to the target. Reflected to attribute. |
| `maxWidth` | `string` | `'300px'` | Maximum width of the tooltip. Set via `max-width` attribute. |
| `trigger` | `string` | `'hover focus'` | Space-separated trigger types. Reflected to attribute. |
| `htmlFor` | `string \| undefined` | `undefined` | ID of an external element to attach the tooltip to. Set via `for` attribute. |

#### Placement Values

`'top'` · `'top-start'` · `'top-end'` · `'right'` · `'right-start'` · `'right-end'` · `'bottom'` · `'bottom-start'` · `'bottom-end'` · `'left'` · `'left-start'` · `'left-end'`

#### Trigger Values

| Trigger | Events Used | Description |
| --- | --- | --- |
| `hover` | `pointerenter` / `pointerleave` | Show on mouse hover. |
| `focus` | `focusin` / `focusout` | Show on keyboard focus. |
| `click` | `click` | Toggle on click. |

Combine triggers with spaces, e.g. `trigger="hover focus"`.

### Events

| Event Name | Detail | Description |
| --- | --- | --- |
| `pi-tooltip-change` | `{ open: boolean }` | Fired when the tooltip is shown or hidden. Bubbles and is composed. |

### Slots

| Slot Name | Description |
| --- | --- |
| _(default)_ | Tooltip content. Accepts text or HTML. |

### CSS Custom Properties

| Property | Default | Description |
| --- | --- | --- |
| `--pi-tooltip-background` | `var(--pi-color-background-application-4, #2c3240)` | Tooltip background color. |
| `--pi-tooltip-color` | `var(--pi-color-font-primary, #fafaff)` | Tooltip text color. |

## Positioning

The tooltip uses [@floating-ui/dom](https://floating-ui.com/) for positioning with the following middleware:

- **offset** — Applies the `offset` property as spacing from the target.
- **flip** — Automatically flips placement if the tooltip would overflow the viewport.
- **shift** — Shifts the tooltip along the axis to stay within the viewport (5px padding).
- **arrow** — Positions the arrow element when `arrow` is enabled.

The tooltip is rendered as a fixed-position element appended to `document.body`.

## Accessibility

- Sets `aria-describedby` on the target element referencing the tooltip.
- Adds `tabindex="0"` to non-focusable target elements.
- The popup element has `role="tooltip"`.
- Pressing Escape closes the tooltip.

## Theming

Customize the appearance using CSS custom properties. This component uses design tokens from `@polarityio/pi-shared` for consistent theming across the component library.

## License

MIT