---
outline: deep
---

# Tooltip

Tooltips are used to display a short text label on hover or focus to describe an element. Commonly used on icon buttons, truncated text, and controls that need additional context.

**`<l-tooltip>`** — Custom Element · Shadow DOM

## Options

### Basic

Reference a trigger element by ID using the `for` attribute.

```html
<button
  id="tooltip-basic"
  class="l-button"
>
  Hover me
</button>
<l-tooltip for="tooltip-basic">Save changes</l-tooltip>
```

### Placement

Set `placement` to control position: `top` (default), `bottom`, `left`, `right`.

```html
<div class="flex flex-wrap items-center gap-4">
  <button
    id="tooltip-top"
    class="l-button"
  >
    Top
  </button>
  <l-tooltip
    for="tooltip-top"
    placement="top"
    >Top</l-tooltip
  >

  <button
    id="tooltip-bottom"
    class="l-button"
  >
    Bottom
  </button>
  <l-tooltip
    for="tooltip-bottom"
    placement="bottom"
    >Bottom</l-tooltip
  >

  <button
    id="tooltip-left"
    class="l-button"
  >
    Left
  </button>
  <l-tooltip
    for="tooltip-left"
    placement="left"
    >Left</l-tooltip
  >

  <button
    id="tooltip-right"
    class="l-button"
  >
    Right
  </button>
  <l-tooltip
    for="tooltip-right"
    placement="right"
    >Right</l-tooltip
  >
</div>
```

### Trigger

Set `trigger` to control activation: `hover focus` (default), `click`, `hover`, `focus`, `manual`.

```html
<button
  id="tooltip-click"
  class="l-button"
>
  Click me
</button>
<l-tooltip
  for="tooltip-click"
  trigger="click"
  >Click-triggered tooltip</l-tooltip
>
```

### Without arrow

Add `without-arrow` to hide the directional arrow.

```html
<button
  id="tooltip-no-arrow"
  class="l-button"
>
  Hover me
</button>
<l-tooltip
  for="tooltip-no-arrow"
  without-arrow
  >No arrow tooltip</l-tooltip
>
```

### Custom color

Set `--background-color` to a base color. Text color is auto-derived from its luminance for readable contrast.

```html
<div class="flex flex-wrap items-center gap-3">
  <button
    id="tooltip-color-yellow"
    class="l-button"
  >
    Yellow
  </button>
  <l-tooltip
    for="tooltip-color-yellow"
    style="--background-color: oklch(90.5% 0.182 98.111)"
  >
    Auto-derived text color
  </l-tooltip>

  <button
    id="tooltip-color-pink"
    class="l-button"
  >
    Pink
  </button>
  <l-tooltip
    for="tooltip-color-pink"
    style="--background-color: oklch(82.3% 0.12 346.018)"
  >
    Auto-derived text color
  </l-tooltip>

  <button
    id="tooltip-color-indigo"
    class="l-button"
  >
    Indigo
  </button>
  <l-tooltip
    for="tooltip-color-indigo"
    style="--background-color: oklch(45.7% 0.24 277.023)"
  >
    Auto-derived text color
  </l-tooltip>
</div>
```

## Examples

### All placements

All 12 placement options with aligned variants (`-start`, `-end`).

```html
<div class="relative mx-auto h-80 w-80">
  <button
    id="p-top-start"
    class="l-button absolute"
    style="left: calc(50% - 70px - 1rem); top: 0"
    aria-label="top-start"
  >
    &#9632;
  </button>
  <l-tooltip
    for="p-top-start"
    placement="top-start"
    >top-start</l-tooltip
  >

  <button
    id="p-top"
    class="l-button absolute"
    style="left: calc(50% - 10px - 1rem); top: 0"
    aria-label="top"
  >
    &#9632;
  </button>
  <l-tooltip
    for="p-top"
    placement="top"
    >top</l-tooltip
  >

  <button
    id="p-top-end"
    class="l-button absolute"
    style="left: calc(50% + 50px - 1rem); top: 0"
    aria-label="top-end"
  >
    &#9632;
  </button>
  <l-tooltip
    for="p-top-end"
    placement="top-end"
    >top-end</l-tooltip
  >

  <button
    id="p-bottom-start"
    class="l-button absolute"
    style="left: calc(50% - 70px - 1rem); bottom: 0"
    aria-label="bottom-start"
  >
    &#9632;
  </button>
  <l-tooltip
    for="p-bottom-start"
    placement="bottom-start"
    >bottom-start</l-tooltip
  >

  <button
    id="p-bottom"
    class="l-button absolute"
    style="left: calc(50% - 10px - 1rem); bottom: 0"
    aria-label="bottom"
  >
    &#9632;
  </button>
  <l-tooltip
    for="p-bottom"
    placement="bottom"
    >bottom</l-tooltip
  >

  <button
    id="p-bottom-end"
    class="l-button absolute"
    style="left: calc(50% + 50px - 1rem); bottom: 0"
    aria-label="bottom-end"
  >
    &#9632;
  </button>
  <l-tooltip
    for="p-bottom-end"
    placement="bottom-end"
    >bottom-end</l-tooltip
  >

  <button
    id="p-left-start"
    class="l-button absolute"
    style="top: calc(50% - 70px - 1rem); left: 0"
    aria-label="left-start"
  >
    &#9632;
  </button>
  <l-tooltip
    for="p-left-start"
    placement="left-start"
    >left-start</l-tooltip
  >

  <button
    id="p-left"
    class="l-button absolute"
    style="top: calc(50% - 10px - 1rem); left: 0"
    aria-label="left"
  >
    &#9632;
  </button>
  <l-tooltip
    for="p-left"
    placement="left"
    >left</l-tooltip
  >

  <button
    id="p-left-end"
    class="l-button absolute"
    style="top: calc(50% + 50px - 1rem); left: 0"
    aria-label="left-end"
  >
    &#9632;
  </button>
  <l-tooltip
    for="p-left-end"
    placement="left-end"
    >left-end</l-tooltip
  >

  <button
    id="p-right-start"
    class="l-button absolute"
    style="top: calc(50% - 70px - 1rem); right: 0"
    aria-label="right-start"
  >
    &#9632;
  </button>
  <l-tooltip
    for="p-right-start"
    placement="right-start"
    >right-start</l-tooltip
  >

  <button
    id="p-right"
    class="l-button absolute"
    style="top: calc(50% - 10px - 1rem); right: 0"
    aria-label="right"
  >
    &#9632;
  </button>
  <l-tooltip
    for="p-right"
    placement="right"
    >right</l-tooltip
  >

  <button
    id="p-right-end"
    class="l-button absolute"
    style="top: calc(50% + 50px - 1rem); right: 0"
    aria-label="right-end"
  >
    &#9632;
  </button>
  <l-tooltip
    for="p-right-end"
    placement="right-end"
    >right-end</l-tooltip
  >
</div>
```

## Accessibility

### Criteria

- **Role** — Popover has `role="tooltip"` with a generated `id`
- **Accessible description** — Trigger receives `aria-describedby` pointing to the tooltip when open
- **Hover state** — Shows on `pointerenter`; safe polygon hover bridge prevents flickering
- **Focus state** — Shows on `focusin`, hides on `focusout`
- **Dismissible** — Closes on `Escape` without moving focus
- **Motion** — Respects `prefers-reduced-motion`

### Rules

- The trigger element must have meaningful text or `aria-label` — the tooltip supplements, it does not replace, the accessible name
- Never put interactive content inside a tooltip; use `<l-popover>` instead
- Tooltip content should be short and text-only

### Keyboard interactions

- `Escape` — Dismisses the tooltip without moving focus
- `Tab` — Moving focus to the trigger shows the tooltip; moving away hides it

## API reference

### Importing

```js
import 'luxen-ui/tooltip';
```

### Attributes & Properties

- **for**: `string` — The HTML id of the element triggering the tooltip.
- **placement**: `Placement` (default: `'top'`) — The preferred placement of the tooltip.
- **distance**: `number` (default: `8`) — The distance in pixels from the target element.
- **open**: `boolean` (default: `false`) — Whether or not the tooltip is visible.
- **without-arrow**: `boolean` (default: `false`) — Hide the directional arrow.
- **trigger**: `string` (default: `'hover focus'`) — Space-separated list of trigger modes: `hover`, `focus`, `click`, `manual`.

### Methods

- **show()**
- **hide()**
- **toggle()**

### CSS custom properties

- `--background-color` — Background color for this tooltip instance. Defaults to the global `--l-tooltip-background-color` token (a neutral inverse surface, dark in light mode / light in dark mode) — override that token to re-skin every tooltip at once.
- `--text-color` — Text color. If unset, auto-derived from `--background-color` luminance.
- `--border-radius` (default: `4px`) — Border radius.
- `--max-width` (default: `180px`) — Maximum width.
- `--arrow-size` (default: `6px`) — Arrow size.
- `--show-duration` (default: `150ms`) — Show animation duration.
- `--hide-duration` (default: `150ms`) — Hide animation duration.