Tooltip

Material Design 3 tooltip component using the Popover API and CSS Anchor Positioning

Tooltip

Tooltips are brief, non-interactive descriptions. The core contract uses native popover="hint", interestfor, and CSS anchor positioning; it does not polyfill missing browser capabilities. Keep critical information inline, and move links, buttons, and other actions to Popover.

Design principle: Every tooltip surface must be an HTML popover. The browser owns visibility through :popover-open; use interestfor with popover="hint" for normal tooltips, or native showPopover() / hidePopover() when application code needs to control one. Do not implement tooltip visibility with wrapper hover/focus selectors, pseudo-elements, data-tip, or open/show classes.

The core intentionally has no arrow: automatic placement may flip at viewport edges, and an arrow tied only to the preferred side would be misleading. Keyboard focus, Escape dismissal, pointer persistence for .tooltip-interactive, and viewport fallback are browser-managed when the relevant features are available. On unsupported browsers, use inline help or an explicit disclosure owned by the consumer; a title attribute is only a limited fallback, not a complete accessible equivalent.

Tooltips display brief, helpful text when users show interest in an element (hover, focus, or long-press).

Breaking change: Tooltips now use the native Popover API (popover="hint") with Interest Invokers (interestfor) and CSS Anchor Positioning. The old wrapper + .tooltip-content markup is no longer supported.

Basic Usage

Pair a trigger (interestfor + anchor-name) with a tooltip surface (popover="hint" + position-anchor):

Basic Tooltip

This is a tooltip

Positions

Preferred placement via position-area. The browser may flip with position-try-fallbacks when space is tight.

Top (Default)

Top Position

Tooltip on top

Bottom

Bottom Position

Tooltip on bottom

Left

Left Position

Tooltip on left

Right Position

Tooltip on right

Color Variants

Primary Tooltip

Primary colored tooltip

Secondary Tooltip

Secondary colored tooltip

Error Tooltip

Error colored tooltip

Light Tooltip

Light themed tooltip

Multi-line Tooltip

Multi-line Tooltip

This is a longer tooltip message that wraps to multiple lines for better readability.

Rich Tooltip

Rich Tooltip

Keyboard Shortcut
Press Ctrl+S to save your work

Delay Variants

Apply delay utilities on the trigger (interest-delay):

Delayed Tooltips

Appears after 300ms
Appears after 500ms

Interactive Tooltip

Use .tooltip-interactive so the surface accepts pointer events. Increase interest-delay-end on the trigger so users can move into the tooltip:

Interactive Tooltip

Learn More
Documentation is available inline in the surrounding page.

Always Open (For Demo)

Call showPopover() once to keep a tooltip open for screenshots/demos:

Always Open

Top tooltip always visible

Browser Support

Capability Core requirement Verification
Popover API and popover="hint" Browser support for the Popover API Chromium, Firefox, and WebKit are configured in the integration suite; this checkout’s system Chromium supports Popover but not Interest Invokers
Interest Invokers (interestfor) Browser support for the experimental Interest Invokers feature Skip when feature detection fails; no runtime polyfill is included
CSS anchor positioning and position-area Browser support for the relevant CSS Anchor Positioning features Use @supports or an application fallback when unavailable

See MDN Popover API, Using interest invokers, and CSS anchor positioning for current compatibility tables. On unsupported browsers, use inline help or an explicit consumer-owned disclosure; title alone is not a complete accessible fallback.

React Example

type TooltipProps = {
  id: string;
  content: string;
  position?: 'top' | 'bottom' | 'left' | 'right';
  children: React.ReactElement;
};

export function Tooltip({ id, content, position = 'top', children }: TooltipProps) {
  const anchor = `--${id}`;
  return (
    <>
      {React.cloneElement(children, {
        interestFor: id,
        style: { ...(children.props.style || {}), anchorName: anchor },
      })}
      <div
        id={id}
        popover="hint"
        className={`tooltip tooltip-${position}`}
        style={{ positionAnchor: anchor }}
      >
        {content}
      </div>
    </>
  );
}

API Reference

Surface classes (on the popover element)

Class Description
.tooltip Base tooltip surface (required with [popover])
.tooltip-top Preferred position-area: top (default)
.tooltip-bottom Preferred position-area: bottom
.tooltip-left Preferred position-area: left
.tooltip-right Preferred position-area: right
.tooltip-primary / .tooltip-secondary / .tooltip-tertiary / .tooltip-info / .tooltip-success / .tooltip-warning / .tooltip-error / .tooltip-light Color variants
.tooltip-multiline Allow wrapping (max-width: 16rem)
.tooltip-rich Rich content (max-width: 20rem)
.tooltip-interactive Enable pointer events on the surface

Trigger utilities

Class Description
.tooltip-delay interest-delay: 300ms
.tooltip-delay-long interest-delay: 500ms

Attributes & CSS

Name Where Description
interestfor Trigger Links interest to the tooltip id
popover="hint" Surface Hint popover (does not dismiss auto popovers)
anchor-name Trigger Explicit named anchor
position-anchor Surface Binds surface to the named anchor
position-area / position-try-fallbacks CSS Preferred placement + flip fallbacks

Rich content

Class Description
.tooltip-rich-title Title in rich tooltip
.tooltip-rich-description Description in rich tooltip

Accessibility

  • Prefer interactive triggers (button, links, form controls) so keyboard focus works with interest invokers
  • Use aria-describedby pointing at the tooltip id when helpful
  • Keep text brief; do not hide critical information only in a tooltip
<button interestfor="demo-tip-a11y" aria-describedby="demo-tip-a11y" style="anchor-name: --demo-tip-a11y">Help</button>
<div id="demo-tip-a11y" popover="hint" class="tooltip" style="position-anchor: --demo-tip-a11y" role="tooltip">
  Click for assistance
</div>
  • Popover - Richer, interactive overlays
  • Snackbar - Brief notification messages
  • Dialog - Modal interactions

See Also