Tooltip

feedbackUSWDS-derivedinteractive

Hover/focus information popup with positioning and viewport edge detection.

Variants

Bottom Tooltip

<div style="padding: 60px;">
  <flex-tooltip data-position="bottom">
    <button type="button" class="flex-tooltip__trigger" aria-describedby="tooltip-21">Hover me (bottom)</button>
    <span class="flex-tooltip__body" id="tooltip-21" role="tooltip">This is a tooltip</span>
  </flex-tooltip>
</div>

Left Tooltip

<div style="padding: 60px;">
  <flex-tooltip data-position="left">
    <button type="button" class="flex-tooltip__trigger" aria-describedby="tooltip-22">Hover me (left)</button>
    <span class="flex-tooltip__body" id="tooltip-22" role="tooltip">This is a tooltip</span>
  </flex-tooltip>
</div>

Right Tooltip

<div style="padding: 60px;">
  <flex-tooltip data-position="right">
    <button type="button" class="flex-tooltip__trigger" aria-describedby="tooltip-23">Hover me (right)</button>
    <span class="flex-tooltip__body" id="tooltip-23" role="tooltip">This is a tooltip</span>
  </flex-tooltip>
</div>

Top Tooltip

<div style="padding: 60px;">
  <flex-tooltip data-position="top">
    <button type="button" class="flex-tooltip__trigger" aria-describedby="tooltip-24">Hover me (top)</button>
    <span class="flex-tooltip__body" id="tooltip-24" role="tooltip">This is a tooltip</span>
  </flex-tooltip>
</div>

Contract

Class mapping

USWDS	Flex	Notes
`usa-tooltip`	`<flex-tooltip> (custom element)`	Container element with relative positioning
`usa-tooltip__trigger`	`.flex-tooltip__trigger`	Element that triggers the tooltip on hover/focus
`usa-tooltip__body`	`.flex-tooltip__body[role="tooltip"]`	Tooltip content with dark background and white text
`usa-tooltip__body--top/bottom/left/right`	`data-position="top/bottom/left/right"`	Position variants via data attribute instead of modifier class

Verified properties

displaypositionbackground-colorcolorborder-radiusfont-sizepadding-toppadding-rightpadding-bottompadding-left

Intentional differences

visibility: ours = hidden (display: none when not visible), USWDS = controlled via is-set/is-visible classes

We use data-visible attribute toggling; USWDS uses JS class toggling

Behavior promises

✓ Tooltip shows on hover (mouseenter) and hides on mouseleave
✓ Tooltip shows on focus and hides on blur
✓ Tooltip is positioned relative to trigger based on data-position
✓ Tooltip flips position when it would overflow viewport

Source CSS

/* flex-tooltip — USWDS Tooltip conformance
   Hover/focus information popup with positioning */

flex-tooltip {
  display: inline-block;
  position: relative;
}

.flex-tooltip__trigger {
  cursor: pointer;
}

.flex-tooltip__body {
  position: absolute;
  display: none;
  background-color: var(--flex-color-tooltip-bg);
  color: var(--flex-color-tooltip-text);
  font-size: 1rem;
  padding: 0.5rem;
  border-radius: 0.25rem;
  white-space: pre;
  inline-size: auto;
  z-index: 100000;
  opacity: 0;
  transition: opacity 0.08s ease-in-out;

  &[data-visible] {
    display: block;
    opacity: 1;
  }

  /* Arrow triangles via ::after */
  &::after {
    content: "";
    position: absolute;
    border: 5px solid transparent;
  }

  /* Top position: arrow points down */
  &[data-position-actual="top"]::after {
    inset-block-start: 100%;
    inset-inline-start: 50%;
    margin-inline-start: -5px;
    border-block-start-color: var(--flex-color-tooltip-bg);
    border-block-end: 0;
  }

  /* Bottom position: arrow points up */
  &[data-position-actual="bottom"]::after {
    inset-block-end: 100%;
    inset-inline-start: 50%;
    margin-inline-start: -5px;
    border-block-end-color: var(--flex-color-tooltip-bg);
    border-block-start: 0;
  }

  /* Left position: arrow points right */
  &[data-position-actual="left"]::after {
    inset-block-start: 50%;
    inset-inline-start: 100%;
    margin-block-start: -5px;
    border-inline-start-color: var(--flex-color-tooltip-bg);
    border-inline-end: 0;
  }

  /* Right position: arrow points left */
  &[data-position-actual="right"]::after {
    inset-block-start: 50%;
    inset-inline-end: 100%;
    margin-block-start: -5px;
    border-inline-end-color: var(--flex-color-tooltip-bg);
    border-inline-start: 0;
  }
}