> For the complete documentation index, see [llms.txt](https://analog.groupthought.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://analog.groupthought.com/reference/alpine/tooltip.md).

# x-tooltip

Directives for tooltips: a hover-and-focus trigger and a panel that floats next to it.

Directives for tooltips: a hover-and-focus trigger and a panel that floats next to it.

| Directive / magic                        | What it does                                                                                             |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `x-tooltip`                              | The root. Holds the open state for the trigger and panel                                                 |
| `x-tooltip="{ isOpen: true }"`           | Options object, passed to the underlying popup                                                           |
| `x-tooltip.disclosure`                   | For a panel with structured content. The panel gets no tooltip role and is not the trigger's description |
| `x-tooltip:trigger`                      | The element the tooltip describes. Opens on hover and on focus                                           |
| `x-tooltip:panel`                        | The floating content (`role="tooltip"`). Opens below the trigger by default                              |
| `x-tooltip:panel.fixed.top.offset.16px…` | Position modifiers. They replace the default position string                                             |
| `x-tooltip:arrow`                        | The arrow. Place it inside the panel; the float logic positions it                                       |
| `$popup`                                 | The popup state, readable anywhere inside the root: `isOpen`, `close()`                                  |

Hover opens the tooltip after 300ms and closes it 300ms after the pointer leaves. Focus opens it and blur closes it. Escape or a mousedown outside also closes it. The trigger points to the panel with `aria-describedby` so screen readers read the tooltip with the trigger.

## Examples

### A basic tooltip

Use `x-tooltip:trigger` and `x-tooltip:panel` inside an `x-tooltip` root:

```html
<div x-tooltip class="contents">
  <div x-tooltip:trigger>…</div>

  <div x-tooltip:panel x-cloak class="fixed w-max">
    In stock
  </div>
</div>
```

Without modifiers the panel sits below the trigger with a 10px offset, flips to the other side when out of room, and keeps a 5px pad from the viewport edge (`absolute.bottom.offset.10px.flip.update.pad.5px`).

### Positioning the panel

Use modifiers on `x-tooltip:panel` to place the panel yourself:

```html
<div x-tooltip:panel.fixed.bottom.offset.5px.flip.shift.update.pad.5px x-cloak>
  …
</div>
```

Modifiers replace the whole default string, so include everything you need. The `core-tooltip` snippet builds this string from its `position` and `offset` parameters.

### An arrow

Use `x-tooltip:arrow` inside the panel for an arrow that tracks the trigger:

```html
<div x-tooltip:panel x-cloak>
  <div x-tooltip:arrow class="h-r6 w-r6 …"></div>
  …
</div>
```

### Styling the open state

Use `$popup.isOpen` with `x-transition` to animate the panel in and out:

```html
<div
  x-tooltip:panel
  :data-open="$popup.isOpen"
  x-transition:enter="animate-in slide-in-from-top-[5px]"
  x-transition:leave="animate-out slide-out-to-top-[5px]"
  x-cloak
>
  …
</div>
```

### A panel with structured content

Use `x-tooltip.disclosure` when the panel holds a list, a table, or several lines:

```html
<div x-tooltip.disclosure class="contents">
  <button type="button" x-tooltip:trigger>$10 off</button>

  <div x-tooltip:panel x-cloak class="fixed w-max">
    <dl>…</dl>
  </div>
</div>
```

A screen reader reads a tooltip as one flat string after the trigger's name, so the structure of a list is lost. With `.disclosure` the panel gets no `role="tooltip"` and the trigger gets no `aria-describedby`. The trigger keeps `aria-expanded` and `aria-controls`, and a screen reader user moves into the panel, which follows the trigger. Use a `button` for the trigger, and give the content its own role and name.

## Options

| Option   | What it does                                                                 |
| -------- | ---------------------------------------------------------------------------- |
| `isOpen` | The open state (default `false`). Accepts a get/set pair for two-way binding |

In Analog, render the `core-tooltip` snippet. It includes the tooltip styles, sizes (`sm`, `lg`), and arrow. The styleguide's color-scheme swatches use it.
