---
title: Tooltip (Vanilla) - USWDS + Tailwind
description: Show a short explanation when someone hovers over or focuses an
  element with a tooltip.
---

# Tooltip

Show a short explanation when someone hovers over or focuses an element with a tooltip.

These examples use the following JavaScript initializers:

* [Tooltip](https://v2.uswds-tailwind.com/docs/vanilla/javascript#tooltip)

## Example

```html
<div class="p-12 space-y-12">
  <div data-scope="tooltip" data-part="root" data-placement="top" class="relative isolate">
    <button
      data-scope="tooltip" data-part="trigger"
      type="button"
      title="Top"
      class="rounded font-bold leading-none text-white px-5 py-3 bg-blue-60v hover:bg-blue-warm-70v active:bg-blue-warm-80v focus:outline-4 focus:outline-offset-4 focus:outline-blue-40v cursor-pointer"
    >
      Show on top
    </button>
    <div
      data-scope="tooltip" data-part="content"
      class="bg-gray-90 rounded-sm text-gray-5 p-2 whitespace-pre z-50 w-auto data-visible:opacity-100 opacity-0 absolute top-(--tooltip-top) bottom-(--tooltip-bottom) left-(--tooltip-left) right-(--tooltip-right) m-(--tooltip-margin) transition-opacity duration-100 ease-in-out not-data-[state=open]:hidden data-wrap:max-w-64 data-wrap:whitespace-normal"
    ></div>
  </div>

   <div data-scope="tooltip" data-part="root" data-placement="right" class="relative isolate">
    <button
      data-scope="tooltip" data-part="trigger"
      type="button"
      title="Right"
      class="rounded font-bold leading-none text-white px-5 py-3 bg-blue-60v hover:bg-blue-warm-70v active:bg-blue-warm-80v focus:outline-4 focus:outline-offset-4 focus:outline-blue-40v cursor-pointer"
    >
      Show on right
    </button>
    <div
      data-scope="tooltip" data-part="content"
      class="bg-gray-90 rounded-sm text-gray-5 p-2 whitespace-pre z-50 w-auto data-visible:opacity-100 opacity-0 absolute top-(--tooltip-top) bottom-(--tooltip-bottom) left-(--tooltip-left) right-(--tooltip-right) m-(--tooltip-margin) transition-opacity duration-100 ease-in-out not-data-[state=open]:hidden data-wrap:max-w-64 data-wrap:whitespace-normal"
    ></div>
  </div>

   <div data-scope="tooltip" data-part="root" data-placement="bottom" class="relative isolate">
    <button
      data-scope="tooltip" data-part="trigger"
      type="button"
      title="Bottom"
      class="rounded font-bold leading-none text-white px-5 py-3 bg-blue-60v hover:bg-blue-warm-70v active:bg-blue-warm-80v focus:outline-4 focus:outline-offset-4 focus:outline-blue-40v cursor-pointer"
    >
      Show on bottom
    </button>
    <div
      data-scope="tooltip" data-part="content"
      class="bg-gray-90 rounded-sm text-gray-5 p-2 whitespace-pre z-50 w-auto data-visible:opacity-100 opacity-0 absolute top-(--tooltip-top) bottom-(--tooltip-bottom) left-(--tooltip-left) right-(--tooltip-right) m-(--tooltip-margin) transition-opacity duration-100 ease-in-out not-data-[state=open]:hidden data-wrap:max-w-64 data-wrap:whitespace-normal"
    ></div>
  </div>

   <div data-scope="tooltip" data-part="root" data-placement="left" class="relative isolate">
    <button
      data-scope="tooltip" data-part="trigger"
      type="button"
      title="Left"
      class="rounded font-bold leading-none text-white px-5 py-3 bg-blue-60v hover:bg-blue-warm-70v active:bg-blue-warm-80v focus:outline-4 focus:outline-offset-4 focus:outline-blue-40v cursor-pointer"
    >
      Show on left
    </button>
    <div
      data-scope="tooltip" data-part="content"
      class="bg-gray-90 rounded-sm text-gray-5 p-2 whitespace-pre z-50 w-auto data-visible:opacity-100 opacity-0 absolute top-(--tooltip-top) bottom-(--tooltip-bottom) left-(--tooltip-left) right-(--tooltip-right) m-(--tooltip-margin) transition-opacity duration-100 ease-in-out not-data-[state=open]:hidden data-wrap:max-w-64 data-wrap:whitespace-normal"
    ></div>
  </div>
</div>
```

## Component API

### Initialization

Run after the component markup exists:

```js
import { tooltipInit } from '@uswds-tailwind/compat/tooltip'

tooltipInit()
```

### Anatomy

Set authored attributes in your HTML. The component manages generated attributes. Types describe HTML attribute values.

#### `root`

Wraps the trigger and tooltip content.

| Attribute | Type | Description |
| - | - | - |
| `data-scope` | `"tooltip"` | **Authored.** Identifies the component scope. |
| `data-part` | `"root"` | **Authored.** Identifies this part. |
| `data-placement` | `"top" \| "bottom" \| "left" \| "right"` | **Authored.** Preferred side: `top`, `bottom`, `left`, or `right`. Defaults to `top`; invalid values fall back to `top`. The `placement` option takes precedence. |

#### `trigger`

The element described by the tooltip.

| Attribute | Type | Description |
| - | - | - |
| `data-part` | `"trigger"` | **Authored.** Identifies this part. |
| `title` | `string` | **Authored.** Optional tooltip text. Copied to the content and removed during initialization. |
| `aria-describedby` | `ID references` | **Generated.** Relationship to tooltip content. |

#### `content`

Author tooltip text here when not using a trigger `title`.

| Attribute | Type | Description |
| - | - | - |
| `data-part` | `"content"` | **Authored.** Identifies this part. |
| `role` | `"tooltip"` | **Generated.** Accessibility role. |
| `aria-hidden` | `"true" \| "false"` | **Generated.** Accessibility visibility. |
| `data-state` | `"open" \| "closed"` | **Generated.** `"open"` or `"closed"`; use for styling. |
| `data-visible` | `presence attribute` | **Generated.** Present after the 20 ms reveal delay; use for the fade-in. |
| `data-placement` | `"top" \| "bottom" \| "left" \| "right"` | **Generated.** Resolved side of the trigger; may differ from the preferred side to fit available space. |
| `data-wrap` | `presence attribute` | **Generated.** Present when width needs to be constrained. |

**CSS variables**

| Variable | Purpose |
| - | - |
| `--tooltip-top`, `--tooltip-bottom` | Vertical position. |
| `--tooltip-left`, `--tooltip-right` | Horizontal position. |
| `--tooltip-margin` | Positioning offset. |
| `--arrow-offset`, `--arrow-transform` | Arrow offset and rotation for the resolved side. |

### Configuration

Pass these JavaScript options to the instance constructor or factory. Authored configuration attributes are read during construction.

| Option | Description |
| - | - |
| `placement` | Preferred side: `top`, `bottom`, `left`, or `right`. Overrides `data-placement`; defaults to `top`. |
| `defaultOpen` | `boolean`. Initial uncontrolled state; defaults to `false`. |
| `open` | `boolean`. Controlled state; your application supplies updates after change callbacks. |
| `id, ids` | Customize the instance identifier and generated element IDs. |

### Methods

| Method | Returns | Description |
| - | - | - |
| `api.setOpen(open)` | `void` | Requests an open-state change. |
| `destroy()` | `void` | Stops the instance; does not restore a removed title or the original HTML. |

```js
import { Tooltip } from '@uswds-tailwind/compat/tooltip'

const tooltip = Tooltip.getOrCreateInstance(
  '[data-scope="tooltip"][data-part="root"]',
)

tooltip.api.setOpen(true)
```

See [initialization and cleanup](https://v2.uswds-tailwind.com/docs/vanilla/javascript#instance-lifecycle).

### Callbacks

| Callback | Payload | When it runs |
| - | - | - |
| `onOpenChange` | `{ open: boolean }` | An open-state change is requested. |

Pass callbacks in instance options. These are JavaScript functions, not emitted DOM events.

### Accessibility

* Give the trigger an accessible name independently of the tooltip.
* Hover or focus reveals it; leaving, blurring, or Escape dismisses it.
* Keep essential instructions visible and interactive controls outside the tooltip.