Skip to main content
USWDS + Tailwind

Tooltip

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

These examples use the following JavaScript initializers:

Example

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
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:

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. 
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.

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.