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
| Slot | Required | Description |
|---|---|---|
text | Yes | Visible label text of the trigger element. |
tooltip | - | CSS-only hint text shown on hover or focus. |
content | Yes | Rich tooltip body content (HTML allowed). Switches to Popover API mode. |
title | - | Optional heading inside a rich tooltip. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
tag | Enum: button, a, em | button | Trigger element to render. |
url | string | # | Href value when the tag is "a". |
placement | Enum: top, right, bottom, left | top | Preferred tooltip position relative to the trigger. |
boundary | string | - | CSS selector for an ancestor that constrains auto-flip. Defaults to the viewport. |
use_autoclose | boolean | true | When true, the tooltip closes on pointer-out or blur. When false, acts as a persistent toggletip. |
group | string | - | Group name for mutual exclusion: opening one tooltip closes others in the same group. |
tooltip_id | string | - | Unique ID linking the trigger to its popover element. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.animated | Motion | Yes | Honors the animations option. |
.still | Motion | - | Forces motion off regardless of the option. |
.flat | Elevation | - | No elevation. |
.raised | Elevation | Yes | Slight elevation. |
Attributes
| Attribute | Set by | Required | Description |
|---|---|---|---|
data-tooltip | Consumer | - | CSS-only hint text shown on hover or focus when no rich content slot is supplied. |
data-tooltip-rich | Consumer | - | Marks the rich tooltip panel element; the toggletip and group-exclusion enhancement binds to it. |
data-popout-anchor | Consumer | - | CSS selector resolved by the popout utility to override the default trigger anchor. |
data-tooltip-group | Consumer | - | Group name for mutual exclusion. Opening one tooltip closes others in the same group. |
data-autoclose | Consumer | - | Controls auto-close on pointer-out or blur. "false" makes the tooltip a persistent toggletip. |
data-tooltip-dismissed | Script | - | 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
| Event | Direction | Description |
|---|---|---|
close-dismiss | Listens | Listened 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-widthstays 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-tooltiprenders 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