toc

Tooltip

Tooltips add context to a button or other element, as a short plain label or a richer panel with a subhead and actions.

edit

Edit

<md-gb-icon-button id="edit" aria-label="Edit">
  <md-gb-icon>edit</md-gb-icon>
</md-gb-icon-button>
<md-gb-tooltip for="edit">Edit</md-gb-tooltip>

Install with shadcn/ui: npx shadcn@latest add https://material-web.dev/3.0/r/md-tooltip.json (setup)

Usage guidelines

Link to “Usage guidelines”

Plain to label. Use a plain tooltip to name an element with no text, such as an icon-only button. Don't add one when the element already has a visible label.
Rich for details. Use a rich tooltip for longer text, such as a definition or an explanation of a new feature, with an optional subhead and up to two text buttons.
Nothing critical. Tooltips are easy to miss, so never hide information people must see. Use a dialog for that.

Anatomy

Link to “Anatomy”

A tooltip points at an anchor element by its id. A rich tooltip can add a subhead and actions.

HTML

<button id="anchor">Storage</button>
<md-gb-tooltip for="anchor" variant="rich" persistent>
  <span slot="subhead">Storage</span>
  Photos and files you keep in your account.
  <md-gb-button slot="action" color="text">Manage</md-gb-button>
</md-gb-tooltip>

document.querySelector('md-gb-tooltip').show();

Examples

Link to “Examples”

Placement

Link to “Placement”

A plain tooltip opens above its anchor and a rich one below it. Set placement to above, below, start or end; it flips when there isn't room. Add caret to point at the anchor.

<md-gb-icon-button id="share" aria-label="Share">
  <md-gb-icon>share</md-gb-icon>
</md-gb-icon-button>
<md-gb-tooltip for="share" placement="below" caret>Share</md-gb-tooltip>

Rich

Link to “Rich”

Set variant="rich" and a subhead. Text buttons go in the action slot.

Grant value

Uses the closing stock price from the day before the grant date. Learn more

<md-gb-button id="grant" color="outlined">Grant value</md-gb-button>
<md-gb-tooltip for="grant" variant="rich" subhead="How it's calculated">
  Uses the closing stock price from the day before the grant date.
  <md-gb-button slot="action" color="text">Learn more</md-gb-button>
</md-gb-tooltip>

Persistent

Link to “Persistent”

A persistent rich tooltip opens when the anchor is clicked and stays open until someone interacts with something else, so people can reach its actions.

What's new

Invite others to a folder and work on files together. Got it

<md-gb-button id="whats-new" color="tonal">What's new</md-gb-button>
<md-gb-tooltip for="whats-new" variant="rich" persistent subhead="Shared folders">
  Invite others to a folder and work on files together.
  <md-gb-button slot="action" color="text">Got it</md-gb-button>
</md-gb-tooltip>

Delays

Link to “Delays”

A tooltip opens right away and closes 1.5 seconds after the pointer leaves. Set show-delay and hide-delay in milliseconds, or add quick to skip the motion.

delete

Delete

<md-gb-icon-button id="delete" aria-label="Delete">
  <md-gb-icon>delete</md-gb-icon>
</md-gb-icon-button>
<md-gb-tooltip for="delete" hide-delay="500">Delete</md-gb-tooltip>

Accessibility

Link to “Accessibility”

A plain tooltip is a tooltip that describes its anchor, and it opens on hover and on keyboard focus. Keep the anchor's own accessible name, such as an aria-label on an icon button.
A rich tooltip with actions is a dialog, so its buttons can be reached with the keyboard.
Escape closes an open tooltip.
Don't put information in a tooltip that people can't find another way, since touch users can't hover.

Compatibility

Link to “Compatibility”

Material Design 3Spec checked59% tokens

58 of 130 buildable spec units are tested, 0 are excluded with a written reason and 0 are uncovered (the target is 0). 24 of 41 token declarations match the spec (59%), and 17 have no spec token.

tooltips on m3.material.io (opens in a new tab) How compliance is measured

BaselineWidely availableChrome 124Edge 124Firefox 125Safari 17.4

The component’s own CSS and JavaScript rely only on web platform features that are Baseline widely available: it works in Chrome 124, Edge 124, Firefox 125, Safari 17.4 and later.

Newer features it uses where the browser has them (progressive enhancements):

@starting-style (opens in a new tab) Newly available degrades safely where it is missing
transition-behavior (opens in a new tab) Newly available degrades safely where it is missing
popover (opens in a new tab) Newly available JavaScript, feature-detected or optional

Browser support Learn more about Baseline (opens in a new tab)

WAI-ARIAaxe and ARIA 1.3 passDialog (Modal)Tooltip

Roles the component renders: dialog (opens in a new tab), tooltip (opens in a new tab).

Follows the WAI-ARIA Authoring Practices: Dialog (Modal) (opens in a new tab), Tooltip (opens in a new tab).

3 rendered states run through axe-core and the WAI-ARIA 1.3 role and attribute rules in a real browser, with no known gaps.

WAI-ARIA 1.3 (opens in a new tab) ARIA Authoring Practices (opens in a new tab) Accessibility

Lighthouse92 · 100 · 100 · 100

Performance
Accessibility
Best practices
SEO

Audits under 90:

First Contentful Paint
Largest Contentful Paint
Largest Contentful Paint element
Eliminate render-blocking resources
Minify JavaScript
Enable text compression
Network dependency tree
Render blocking requests

Lighthouse 12.8.2 (desktop, 2026-11-08) on the component alone: its first example on a page of its own, without this site's shell. The modules are the development build (not bundled or minified), so the performance score is indicative.

Open the test page About Lighthouse (opens in a new tab)

API reference

Link to “API reference”

<md-gb-tooltip>

Link to “<md-gb-tooltip>”

A Material Design plain or rich tooltip.

Properties

Link to “Properties”

Property	Attribute	Type	Default
`align` How the tooltip lines up with its anchor along the placement side: `center` (plain default) or `start` (rich default). A rich tooltip can be `center`ed below its anchor on desktop.	`align`	`""`	"start"
`caret` Whether to draw a caret pointing at the anchor.	`caret`	`boolean`	`false`
`hideDelay` Delay before hiding after the pointer leaves, in milliseconds.	`hide-delay`	`number`	`TOOLTIP_HIDE_DELAY_MS`
`htmlFor` The id of the anchor element, in the same root as the tooltip.	`for`	`string`	`''`
`noBoundary` Plain only: the anchor has no visual boundary, such as a text baseline, so the tooltip sits 8dp from it instead of 4dp.	`no-boundary`	`boolean`	`false`
`open` Whether the tooltip is open.	`open`	`boolean`
`persistent` Rich only: opens when the anchor is clicked instead of on hover / focus, and stays open until the user interacts with another element.	`persistent`	`boolean`	`false`
`placement` Preferred side of the anchor. Defaults to `above` for plain tooltips and `below` for rich ones. Flips when there isn't room.	`placement`	`""`	TooltipPlacement
`quick` Skips the open / close animation.	`quick`	`boolean`	`false`
`showDelay` Hover delay before showing, in milliseconds.	`show-delay`	`number`	`TOOLTIP_SHOW_DELAY_MS`
`subhead` Rich only: subhead text. Replaced by content in the `subhead` slot.	`subhead`	`string`	`''`
`variant` Plain or rich.	`variant`	`TooltipVariant`	`TOOLTIP_VARIANTS.plain`

Slots

Link to “Slots”

Slot	Description
default	The supporting text.
`action`	Rich tooltip text buttons (up to two), e.g. `<md-gb-button color="text">`.
`subhead`	Rich tooltip subhead; replaces the `subhead` attribute.

Events

Link to “Events”

Event	Description
`close` CustomEvent<{reason: string}>	Fired before the tooltip closes. Cancelable.
`closed` CustomEvent<{reason: string}>	Fired after the tooltip closes.
`open` Event	Fired before the tooltip opens. Cancelable.
`opened` Event	Fired after the tooltip opens.

Methods

Link to “Methods”

Method	Description
`hide` () => void	Closes the tooltip.
`reposition` () => void	Recomputes the tooltip's position next to its anchor.
`show` () => void	Opens the tooltip, closing any other open tooltip.

CSS parts

Link to “CSS parts”

Part	Description
`::part(actions)`	The actions container.
`::part(caret)`	The caret.
`::part(subhead)`	The subhead container.
`::part(supporting-text)`	The supporting text container.
`::part(tooltip)`	The tooltip surface.

CSS custom properties

Link to “CSS custom properties”

Property	Description
`--action-label-text`	Rich action typography.
`--action-label-text-axes`	Rich action font variation settings.
`--action-label-text-color`	Rich action label color.
`--action-label-text-tracking`	Rich action letter spacing.
`--actions-gap`	Space between rich actions.
`--actions-padding-block-end`	Rich container bottom padding below actions.
`--actions-spacing`	Space above the rich actions.
`--anchor-spacing`	Distance between the anchor and the tooltip (or its caret).
`--caret-height`	Caret height.
`--caret-width`	Caret base width.
`--container-color`	Container color.
`--container-elevation`	Container box shadow.
`--container-shape`	Container corner radius.
`--max-width`	Maximum container width.
`--min-height`	Minimum container height.
`--min-width`	Minimum container width.
`--padding-block`	Container block padding.
`--padding-inline`	Container inline padding.
`--subhead`	Rich subhead typography.
`--subhead-axes`	Rich subhead font variation settings.
`--subhead-color`	Rich subhead color.
`--subhead-spacing`	Space below the rich subhead.
`--subhead-tracking`	Rich subhead letter spacing.
`--supporting-text`	Supporting text typography.
`--supporting-text-axes`	Supporting text font variation settings.
`--supporting-text-color`	Supporting text color.
`--supporting-text-tracking`	Supporting text letter spacing.
`--viewport-margin`	Minimum distance from the viewport edges.