Rich tooltip

A rich tooltip shows a heading, a few lines of text and an optional action beside the element it describes. Left alone, it follows hover and focus; made persistent, it stays open until dismissed, which gives a reader time to use its action. Hover, focus, or press any button below to open its tooltip.

Shortcuts Work faster Press ? anywhere to list every keyboard shortcut. Open the list Storage Almost full You have used 9.4 of 10 GB. Old exports are the quickest thing to clear. Review files Sync Paused on cellular Large files wait for Wi-Fi so they never eat your data plan. Sync now Dark mode Follows your device It switches at sunset unless you pick a side. Pick a side Invite Add a teammate They can edit this folder, but never see billing. Send invite Beta New this week Drafts now save themselves every few seconds. See what changed Export Take it with you Download every note as plain Markdown, one file each. Start export Backups Last backup: 2 AM Nightly copies are kept for 30 days, then thinned to one a week. Restore a copy Focus Quiet for 25 minutes Notifications wait until the timer ends. Urgent ones still get through. Start timer Fonts Reads better Pick a typeface with taller letters if small text tires your eyes. Open settings Share Anyone with the link Viewers can comment but not edit. You can switch the link off at any time. Copy link Offline Available offline This notebook is saved on this device and syncs when you are back. Manage downloads Templates Start from a layout Meeting notes, a weekly plan, and a trip list are ready to fill in. Browse templates Tags Find it later Add up to five tags. Search treats them like words in the note. Add a tag Voice Hold to talk Dictation turns speech into text as you speak, in 30 languages. Try it History Every edit, kept Step back to any version from the last 90 days. Open history Lock Needs your fingerprint Locked notes stay hidden until you unlock them. Lock this note Pin Keep it on top Pinned notes stay above the rest of the list. Pin it Archive Out of sight, not gone Archived notes leave your list and stay searchable. See archive Trash Emptied after 30 days Deleted notes wait here first, so a slip is never final. Empty trash now Help Stuck? A person answers within a day, usually faster. Contact support Feedback Say what you think One question, about a minute, and every answer is read. Take the survey

Reference docs⁠

BlazorReactWebOverviewExamplesAPIStylingAccessibility

Choosing a pop-up surface⁠

Five kinds of surface open over the page for a moment. Each suits a different job:

  • Dialog: a question the reader must answer before going on, such as Discard unsaved changes?
  • Popover: extra content opened from a control and dismissed by clicking away, such as a small settings panel.
  • Menu: a short list of commands opened from a button, such as Rename, Duplicate, Delete.
  • Plain tooltip: a short label shown on hover or focus, such as what an icon button does.
  • Rich tooltip: a heading, a few lines of text and an optional action shown next to the element it describes, such as what a new feature does.

Three jobs belong elsewhere. A message about something that just happened is a toast, content that stays on the page is a card, and a short set of creation actions opened from a floating button is a FAB menu.

Choosing a variant⁠

Two behaviors set how long a rich tooltip stays and who decides:

  • Standard: opens on hover, focus, or a click on the anchor, and closes when the reader moves away or presses outside it; suits an explanation a reader skims, such as what a new feature does.
  • Persistent: set persistent; opens on a click or tap on the anchor and stays until dismissed; suits text or an action a reader needs time with, such as a link to the full guide.

Built in⁠

  • position places the tooltip against its anchor in one of eight positions.
  • A short grace period keeps the tooltip open while the pointer travels from the anchor to its action.
  • The sub-heading and content describe the anchor to assistive technology.
  • A persistent tooltip's button anchor is announced as expanded while the tooltip is open.
  • anchor points the tooltip at an element already on the page, and show() and hide() open and close it from code.
  • Escape and a press outside both close it.

Hidden content renders when first shown⁠

A rich tooltip keeps its content and actions hidden until it shows. Each showing looks like the first, and your own content and actions are untouched. Wait for updateComplete and the hidden content has rendered, so your code can reach it at once. See Hidden content renders when first shown.

Using rich tooltips well⁠

  • Use a rich tooltip for extra information and actions about an element or a new feature.
  • Give the sub-heading one line, and always include it when the tooltip appears on page load.
  • Offer at most two short text buttons, side by side.
  • Leave persistent tooltips off icon buttons.
  • Put critical information in a dialog, because a tooltip is easy to miss.
  • Use a plain tooltip when a short label is all the element needs.

These rules follow Material 3 Expressive's guidance for tooltips, on material.io.

Position⁠

position sets where the tooltip sits relative to its anchor, in one of eight positions. Omit it and the tooltip takes the position from your style configuration, which is end-center unless you have changed it. Choose a position, then hover, focus, or press the anchor.

Content⁠

A rich tooltip takes a small heading in the sub-heading slot, its text in the content slot and up to two text buttons in the action slot. The anchor goes in the default slot. A screen reader reads the sub-heading and content after the anchor's name, but not the action, so put nothing essential in the action alone.

Persistent⁠

Set persistent and the tooltip opens only when the reader activates the anchor. It stays open until the anchor is activated again, Escape is pressed, or the reader presses outside it. Hover and focus alone no longer open it. Use it when the tooltip holds an action a reader needs time to reach.

Anchors and methods⁠

By default the tooltip wraps its anchor. Set anchor to the id of an element already on the page and the tooltip positions against that element instead. An id resolves within one root node. When an id cannot find the anchor, set external-anchor and assign the element in script.

show() and hide() open and close the tooltip from script. With an anchor set by anchor, they are how a persistent tooltip opens and closes, as the two buttons below do.

Properties⁠

PropertyAttributeTypeDescription
anchoranchorstringThe id of the element the tooltip attaches to. The element is found in the same page or component as the tooltip, and the tooltip does not wrap it.Takes precedence over the anchorElement property.Note: an id cannot name an element inside another component. Use external-anchor with the anchorElement property for that case. See Anchors and methods.
anchorElementHTMLElementThe element the tooltip attaches to and positions against.Resolves in precedence order: the anchor idref, then an element assigned to this property, then the content the tooltip wraps.Assign an element, with external-anchor, to anchor to one an id cannot find, such as an element inside another component.
externalAnchorexternal-anchorbooleandefault falseSet this when the anchor is not slotted into the tooltip: the tooltip attaches to the element anchorElement resolves to, and the default slot is ignored. See Anchors and methods.
persistentpersistentbooleandefault falseOpens on a click or tap on a slotted anchor and stays open until dismissed, rather than following hover and focus. With anchor or external-anchor, open and close it with show() and hide(). Use it when the tooltip holds actions or text a reader needs time with. See Persistent.
positionpositionstart-start, start-center, start-end, center-start, center-end, end-start, end-center, end-endTooltipPositionTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip sits relative to its anchor, named as the block position then the inline position: end-center is below the anchor and centered. The inline position mirrors in right-to-left text. See Position.

Setting persistent to false while the tooltip is open closes it. With an anchor set from outside the tooltip, only show() and hide() toggle a persistent tooltip.

Slots⁠

SlotDescription
(default)The anchor element. Not used, and not rendered, when anchor or external-anchor supplies the anchor.
sub-headingA small heading above the content.
contentThe tooltip's main content, as text or elements.
actionA button or other action the reader can take from the tooltip.

Methods⁠

MethodReturnsDescription
hide()voidCloses the tooltip. A pending hover or focus delay is canceled, and focus inside the tooltip returns to the anchor.
show()voidOpens the tooltip at the current anchor. A pending hover or focus delay is canceled, so this call decides.

Props⁠

PropTypeDescription
anchorstringThe id of the element the tooltip attaches to. The element is found in the same page or component as the tooltip, and the tooltip does not wrap it.Takes precedence over the anchorElement prop.Note: an id cannot name an element inside another component. Use externalAnchor with the anchorElement prop for that case. See Anchors and methods.
anchorElementHTMLElementThe element the tooltip attaches to and positions against.Resolves in precedence order: the anchor idref, then an element assigned to this property, then the content the tooltip wraps.Assign an element, with externalAnchor, to anchor to one an id cannot find, such as an element inside another component.
externalAnchorbooleandefault falseSet this when the anchor is not slotted into the tooltip: the tooltip attaches to the element anchorElement resolves to, and the default slot is ignored. See Anchors and methods.
persistentbooleandefault falseOpens on a click or tap on a slotted anchor and stays open until dismissed, rather than following hover and focus. With anchor or externalAnchor, open and close it with show() and hide(). Use it when the tooltip holds actions or text a reader needs time with. See Persistent.
positionTooltipPositionTypeTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip sits relative to its anchor, named as the block position then the inline position: end-center is below the anchor and centered. The inline position mirrors in right-to-left text. See Position.

Setting persistent to false while the tooltip is open closes it. With an anchor set from outside the tooltip, only show() and hide() toggle a persistent tooltip.

Children⁠

ChildDescription
childrenThe anchor element. Not used, and not rendered, when anchor or externalAnchor supplies the anchor.
a child with slot="sub-heading"A small heading above the content.
a child with slot="content"The tooltip's main content, as text or elements.
a child with slot="action"A button or other action the reader can take from the tooltip.

Methods⁠

Call these on the element the ref holds.

MethodReturnsDescription
hide()voidCloses the tooltip. A pending hover or focus delay is canceled, and focus inside the tooltip returns to the anchor.
show()voidOpens the tooltip at the current anchor. A pending hover or focus delay is canceled, so this call decides.

Parameters⁠

ParameterTypeDescription
Anchorstring?The id of the element the tooltip attaches to. The element is found in the same page or component as the tooltip, and the tooltip does not wrap it.Takes precedence over the AnchorElement parameter.Note: an id cannot name an element inside another component. Use ExternalAnchor with the AnchorElement parameter for that case. See Anchors and methods.
AnchorElementElementReference?The element the tooltip attaches to and positions against.Resolves in precedence order: the Anchor idref, then an element assigned to this property, then the content the tooltip wraps.Assign an element, with ExternalAnchor, to anchor to one an id cannot find, such as an element inside another component.
ExternalAnchorbool?default falseSet this when the anchor is not slotted into the tooltip: the tooltip attaches to the element AnchorElement resolves to, and the default slot is ignored. See Anchors and methods.
Persistentbool?default falseOpens on a click or tap on a slotted anchor and stays open until dismissed, rather than following hover and focus. With Anchor or ExternalAnchor, open and close it with show() and hide(). Use it when the tooltip holds actions or text a reader needs time with. See Persistent.
PositionTooltipPosition?TooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip sits relative to its anchor, named as the block position then the inline position: end-center is below the anchor and centered. The inline position mirrors in right-to-left text. See Position.

Setting persistent to false while the tooltip is open closes it. With an anchor set from outside the tooltip, only show() and hide() toggle a persistent tooltip.

Render fragments⁠

Once you write Action or any other fragment as a child element, the main content must go in an explicit <ChildContent> too; markup beside <Action> is a compile error. Here ChildContent is: The anchor element.

<CbRichTooltip>
    <Action>Content</Action>
    <ChildContent>Main content</ChildContent>
</CbRichTooltip>
content_copy
ParameterTypeDescription
ActionRenderFragment?A button or other action the reader can take from the tooltip.
ChildContentRenderFragment?The anchor element. Not used, and not rendered, when Anchor or ExternalAnchor supplies the anchor.
ContentRenderFragment?The tooltip's main content, as text or elements.
SubHeadingRenderFragment?A small heading above the content.

Inputs⁠

InputTypeDescription
anchorstringThe id of the element the tooltip attaches to. The element is found in the same page or component as the tooltip, and the tooltip does not wrap it.Takes precedence over the anchorElement input.Note: an id cannot name an element inside another component. Use externalAnchor with the anchorElement input for that case. See Anchors and methods.
anchorElementHTMLElementThe element the tooltip attaches to and positions against.Resolves in precedence order: the anchor idref, then an element assigned to this property, then the content the tooltip wraps.Assign an element, with externalAnchor, to anchor to one an id cannot find, such as an element inside another component.
externalAnchorbooleandefault falseSet this when the anchor is not slotted into the tooltip: the tooltip attaches to the element anchorElement resolves to, and the default slot is ignored. See Anchors and methods.
persistentbooleandefault falseOpens on a click or tap on a slotted anchor and stays open until dismissed, rather than following hover and focus. With anchor or externalAnchor, open and close it with show() and hide(). Use it when the tooltip holds actions or text a reader needs time with. See Persistent.
positionTooltipPositionTypeTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip sits relative to its anchor, named as the block position then the inline position: end-center is below the anchor and centered. The inline position mirrors in right-to-left text. See Position.

Setting persistent to false while the tooltip is open closes it. With an anchor set from outside the tooltip, only show() and hide() toggle a persistent tooltip.

Content projection⁠

ContentDescription
content with no slotThe anchor element. Not used, and not rendered, when anchor or externalAnchor supplies the anchor.
an element with slot="sub-heading"A small heading above the content.
an element with slot="content"The tooltip's main content, as text or elements.
an element with slot="action"A button or other action the reader can take from the tooltip.

Methods⁠

Call these on the element the ref holds.

MethodReturnsDescription
hide()voidCloses the tooltip. A pending hover or focus delay is canceled, and focus inside the tooltip returns to the anchor.
show()voidOpens the tooltip at the current anchor. A pending hover or focus delay is canceled, so this call decides.

Props⁠

PropTypeDescription
anchorstringThe id of the element the tooltip attaches to. The element is found in the same page or component as the tooltip, and the tooltip does not wrap it.Takes precedence over the anchorElement prop.Note: an id cannot name an element inside another component. Use externalAnchor with the anchorElement prop for that case. See Anchors and methods.
anchorElementHTMLElementThe element the tooltip attaches to and positions against.Resolves in precedence order: the anchor idref, then an element assigned to this property, then the content the tooltip wraps.Assign an element, with externalAnchor, to anchor to one an id cannot find, such as an element inside another component.
externalAnchorbooleandefault falseSet this when the anchor is not slotted into the tooltip: the tooltip attaches to the element anchorElement resolves to, and the default slot is ignored. See Anchors and methods.
persistentbooleandefault falseOpens on a click or tap on a slotted anchor and stays open until dismissed, rather than following hover and focus. With anchor or externalAnchor, open and close it with show() and hide(). Use it when the tooltip holds actions or text a reader needs time with. See Persistent.
positionTooltipPositionTypeTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip sits relative to its anchor, named as the block position then the inline position: end-center is below the anchor and centered. The inline position mirrors in right-to-left text. See Position.

Setting persistent to false while the tooltip is open closes it. With an anchor set from outside the tooltip, only show() and hide() toggle a persistent tooltip.

Slots⁠

SlotDescription
defaultThe anchor element. Not used, and not rendered, when anchor or externalAnchor supplies the anchor.
actionA button or other action the reader can take from the tooltip.
contentThe tooltip's main content, as text or elements.
sub-headingA small heading above the content.

Methods⁠

Call these on the element the ref holds.

MethodReturnsDescription
hide()voidCloses the tooltip. A pending hover or focus delay is canceled, and focus inside the tooltip returns to the anchor.
show()voidOpens the tooltip at the current anchor. A pending hover or focus delay is canceled, so this call decides.

Props⁠

PropTypeDescription
anchorstringThe id of the element the tooltip attaches to. The element is found in the same page or component as the tooltip, and the tooltip does not wrap it.Takes precedence over the anchorElement prop.Note: an id cannot name an element inside another component. Use externalAnchor with the anchorElement prop for that case. See Anchors and methods.
anchorElementHTMLElementThe element the tooltip attaches to and positions against.Resolves in precedence order: the anchor idref, then an element assigned to this property, then the content the tooltip wraps.Assign an element, with externalAnchor, to anchor to one an id cannot find, such as an element inside another component.
externalAnchorbooleandefault falseSet this when the anchor is not slotted into the tooltip: the tooltip attaches to the element anchorElement resolves to, and the default slot is ignored. See Anchors and methods.
persistentbooleandefault falseOpens on a click or tap on a slotted anchor and stays open until dismissed, rather than following hover and focus. With anchor or externalAnchor, open and close it with show() and hide(). Use it when the tooltip holds actions or text a reader needs time with. See Persistent.
positionTooltipPositionTypeTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip sits relative to its anchor, named as the block position then the inline position: end-center is below the anchor and centered. The inline position mirrors in right-to-left text. See Position.

Setting persistent to false while the tooltip is open closes it. With an anchor set from outside the tooltip, only show() and hide() toggle a persistent tooltip.

Snippets⁠

SnippetDescription
childrenThe anchor element. Not used, and not rendered, when anchor or externalAnchor supplies the anchor.
subHeadingSnippetA small heading above the content.
contentSnippetThe tooltip's main content, as text or elements.
actionSnippetA button or other action the reader can take from the tooltip.

Methods⁠

Call these on the element the ref holds.

MethodReturnsDescription
hide()voidCloses the tooltip. A pending hover or focus delay is canceled, and focus inside the tooltip returns to the anchor.
show()voidOpens the tooltip at the current anchor. A pending hover or focus delay is canceled, so this call decides.

A value is what the token defaults to; selecting it copies the token's name.

Tokens⁠

TokenValue
--ct-rich-tooltip-action-label-text-color--ct-sys-color-primary --ct-rich-tooltip-action-label-text-color
--ct-rich-tooltip-action-label-text-font--ct-sys-typescale-label-large-font --ct-rich-tooltip-action-label-text-font
--ct-rich-tooltip-action-label-text-line-height--ct-sys-typescale-label-large-line-height --ct-rich-tooltip-action-label-text-line-height
--ct-rich-tooltip-action-label-text-size--ct-sys-typescale-label-large-size --ct-rich-tooltip-action-label-text-size
--ct-rich-tooltip-action-label-text-tracking--ct-sys-typescale-label-large-tracking --ct-rich-tooltip-action-label-text-tracking
--ct-rich-tooltip-action-label-text-weight--ct-sys-typescale-label-large-weight --ct-rich-tooltip-action-label-text-weight
--ct-rich-tooltip-container-color--ct-sys-color-surface-container --ct-rich-tooltip-container-color
--ct-rich-tooltip-container-elevation2 --ct-rich-tooltip-container-elevation
--ct-rich-tooltip-container-max-width280px --ct-rich-tooltip-container-max-width
--ct-rich-tooltip-subhead-color--ct-sys-color-on-surface-variant --ct-rich-tooltip-subhead-color
--ct-rich-tooltip-subhead-font--ct-sys-typescale-title-small-font --ct-rich-tooltip-subhead-font
--ct-rich-tooltip-subhead-line-height--ct-sys-typescale-title-small-line-height --ct-rich-tooltip-subhead-line-height
--ct-rich-tooltip-subhead-size--ct-sys-typescale-title-small-size --ct-rich-tooltip-subhead-size
--ct-rich-tooltip-subhead-tracking--ct-sys-typescale-title-small-tracking --ct-rich-tooltip-subhead-tracking
--ct-rich-tooltip-subhead-weight--ct-sys-typescale-title-small-weight --ct-rich-tooltip-subhead-weight
--ct-rich-tooltip-supporting-text-color--ct-sys-color-on-surface-variant --ct-rich-tooltip-supporting-text-color
--ct-rich-tooltip-supporting-text-font--ct-sys-typescale-body-medium-font --ct-rich-tooltip-supporting-text-font
--ct-rich-tooltip-supporting-text-line-height--ct-sys-typescale-body-medium-line-height --ct-rich-tooltip-supporting-text-line-height
--ct-rich-tooltip-supporting-text-size--ct-sys-typescale-body-medium-size --ct-rich-tooltip-supporting-text-size
--ct-rich-tooltip-supporting-text-tracking--ct-sys-typescale-body-medium-tracking --ct-rich-tooltip-supporting-text-tracking
--ct-rich-tooltip-supporting-text-weight--ct-sys-typescale-body-medium-weight --ct-rich-tooltip-supporting-text-weight

Names and states⁠

A screen reader announces a rich tooltip as a tooltip, or as a dialog while persistent is set, as the WAI-ARIA Authoring Practices: Tooltip pattern describes.

  • The tooltip is named by its own content.
  • A screen reader reads the sub-heading and content text after the anchor's name, as a description. Text that only repeats the name is skipped, and the action slot is never part of the description.
  • A persistent tooltip describes nothing. It is a disclosure the anchor controls, so a screen reader announces a button, link, or other button-like anchor as expanded while the tooltip is open.
  • The tooltip never names its anchor. Give the anchor its own accessible name, and anchor on a control that takes keyboard focus, such as a button.
  • A persistent tooltip on an anchor that is not button-like logs a warning. Enter or Space on a slotted anchor opens it, as a click does.

Keyboard and focus⁠

Key Action
Tab Moves focus onto the anchor, which opens a standard tooltip, and then onto the action, which keeps the tooltip open.
Enter, Space Open or close a persistent tooltip from a slotted anchor that is not a button.
Escape Closes a visible tooltip.

On a button anchor, Enter and Space are the button's own behavior, and its click toggles a persistent tooltip.

  • When the tooltip closes with focus inside it, focus returns to the anchor.
  • A standard tooltip also opens on a click, and a press outside closes it.
  • The tooltip draws no focus ring of its own; the anchor and the action are controls you supply.

Pointer and touch⁠

  • A click or tap on the anchor opens a standard tooltip and toggles a persistent one.
  • The tooltip stays up for a grace period after the pointer leaves the anchor, so the pointer can reach the action.
  • The tooltip sets no touch target size. The anchor and the action are your controls, so give each a target of at least 24 by 24 pixels, as WCAG 2.5.8 asks.

Display settings⁠

  • Reduced motion: the fade is skipped, and the tooltip appears and disappears at once.
  • Right-to-left: the tooltip's position flips with the reading direction, and its content keeps the direction of the surrounding text.

Standards⁠

With its defaults, the rich tooltip meets one WCAG 2.2 success criterion:

  • 1.4.13 Content on Hover or Focus (AA)

Two more depend on how you use it:

  • 2.4.7 Focus Visible (AA): give the anchor and the action a visible focus indicator, as a button does.
  • 2.5.8 Target Size (Minimum) (AA): give the anchor and the action a target of at least 24 by 24 pixels.