Skip to main content

Tooltip

Contextual overlay anchored to a trigger element, built on the native Popover API. Comes in two flavors: a CSS-only text hint driven by data-tooltip for short labels, and a JS-enhanced rich tooltip that supports titles, HTML content, auto-flip positioning, and toggletip behavior (explicit dismiss).

Usage​

When to use

  • Short supplementary labels for icon-only buttons
  • Brief explanations of a term or control on hover/focus
  • Toggletips - click-to-open overlays with richer help content

When not to use

  • Essential information that users must read to complete a task
  • Long-form content or forms - use a modal or drawer
  • Mobile-first flows where hover isn't available - prefer inline text or a disclosure

Do

  • Keep tooltip text short and specific
  • Pair icon-only buttons with a tooltip and an accessible name
  • Use data-autoclose="false" when the content needs to be read carefully or interacted with

Don't

  • Put critical actions inside a hover tooltip
  • Nest tooltips inside tooltips
  • Rely on tooltips as the only source of a control's label

API​

Slots​

SlotRequiredDescription
textYesVisible label text of the trigger element.
tooltip-CSS-only hint text shown on hover or focus.
contentYesRich tooltip body content (HTML allowed). Switches to Popover API mode.
title-Optional heading inside a rich tooltip.

Props​

PropTypeDefaultDescription
tagEnum: button, a, embuttonTrigger element to render.
urlstring#Href value when the tag is "a".
placementEnum: top, right, bottom, lefttopPreferred tooltip position relative to the trigger.
boundarystring-CSS selector for an ancestor that constrains auto-flip. Defaults to the viewport.
use_autoclosebooleantrueWhen true, the tooltip closes on pointer-out or blur. When false, acts as a persistent toggletip.
groupstring-Group name for mutual exclusion: opening one tooltip closes others in the same group.
tooltip_idstring-Unique ID linking the trigger to its popover element.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.animatedMotionYesHonors the animations option.
.stillMotion-Forces motion off regardless of the option.
.flatElevation-No elevation.
.raisedElevationYesSlight elevation.

Attributes​

AttributeSet byRequiredDescription
data-tooltipConsumer-CSS-only hint text shown on hover or focus when no rich content slot is supplied.
data-tooltip-richConsumer-Marks the rich tooltip panel element; the toggletip and group-exclusion enhancement binds to it.
data-popout-anchorConsumer-CSS selector resolved by the popout utility to override the default trigger anchor.
data-tooltip-groupConsumer-Group name for mutual exclusion. Opening one tooltip closes others in the same group.
data-autocloseConsumer-Controls auto-close on pointer-out or blur. "false" makes the tooltip a persistent toggletip.
data-tooltip-dismissedScript-Set on a hint trigger when Escape dismisses the bubble while the trigger keeps hover or focus. Cleared when the trigger is hovered or focused again.

Events​

EventDirectionDescription
close-dismissListensListened on the rich-tooltip element. Closes the tooltip when a descendant dismiss button dispatches this event.

Examples​

Text hint​

A one-line hint on four kinds of trigger - a button, a link, an emphasized word inside a sentence, and a bare glyph.

Rich content​

A panel carrying a title and a paragraph rather than a single line of text.

Click trigger​

Panels opened by click and held open until dismissed, grouped so opening one closes its siblings.

Positioning​

Every placement value, alongside the same set inside a boundary tight enough to force each panel to flip.

Accessibility​

  • WCAG 2.2 AA
  • CSS-only hint trigger has an accessible name (visible label or aria-label); the hint supplements, never replaces, that name
  • Persistent tooltip / toggletip is keyboard reachable, opened with Enter or Space on the trigger, and dismissed with Escape
  • Escape also dismisses a CSS-only hint and a hover tooltip without moving the pointer or the keyboard focus; the tooltip returns the next time the trigger is hovered or focused
  • Hint text wraps inside the bubble, so a hint longer than --tooltip-max-width stays readable rather than spilling past the edge
  • Focus returns to the trigger on close
  • Rich tooltip content is exposed through the native Popover API so assistive technology can reach it; CSS-only hints are presentational and rely on the trigger's own accessible name (see Accessibility implementation for the assistive-only fallback when the hint text must be announced)

Dependencies​

  • close - used as the dismiss control when data-autoclose="false" and rich content is shown

Progressive enhancement​

  • No JS: CSS-only hint via data-tooltip renders as a simple positioned pseudo-element; the Popover API itself is native and works without any custom JS for the core open/close
  • With JS: auto-flip placement when the tooltip would overflow, group management via data-tooltip-group, and coordinated dismissal when paired with the close component in persistent mode
  • How to enable: include the tooltip enhancement script; no per-instance opt-in required
  • close - dismiss control for persistent tooltips
  • modal - heavier overlay for critical interactions
  • dropdown - menu overlay anchored to a trigger