Plain tooltip

A plain tooltip shows a short text hint beside the element it describes, on hover or keyboard focus. Its position, one of eight, decides which part of the page the hint covers, and it moves itself back into view near a screen edge. Hover or focus a control in the grid to read what each one does.

Publish Makes the draft public Bold (Ctrl+B) Export Saves the visible rows as a CSV file Mutes your microphone Adds it to your favorites Invite Sends an invitation by email Undo Brings back what you just deleted Moves it to the trash Share Copies a link anyone can open Save Saves a copy to this device Prints the current page Filter Shows only the rows that match Reply Replies to the sender only Reloads the latest data Silences alerts for this thread Archive Moves the thread out of your inbox Send Sends your message now Saves your place Rename Gives this file a new name Copies the link Download Saves the file to your downloads folder Preview Shows the page as readers see it Changes how this page behaves Remind Brings this back tomorrow morning Stops anyone else editing

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.

Built in⁠

  • Eight position values place the hint above, beside, or below its anchor, and the inline half mirrors in right-to-left text.
  • A pointer that rests on the anchor opens the hint, keyboard focus opens it at once, and Escape closes it.
  • The hint stays open while the pointer crosses the gap onto it, so a reader can move to it without losing it.
  • Assistive technology reads the hint as the anchor's description.
  • anchor points the tooltip at an element already on the page, so the element needs no wrapper.
  • show and hide open and close the hint from code.

Hidden content renders when first shown⁠

A plain tooltip keeps its text hidden until it shows. Each showing looks like the first, because nothing carries over from the last time it was hidden. 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 plain tooltips well⁠

  • Give an icon-only button its own aria-label, and use a plain tooltip to add detail such as a shortcut.
  • Leave the tooltip off an element that already has label text.
  • Keep the text brief, on one line, and limited to one piece of information.
  • Put critical information in a dialog, because a tooltip is easy to miss.
  • Show one tooltip at a time, so two hints never compete for attention.
  • Use a rich tooltip for extra information or an action.

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

Position⁠

position places the hint on any side or corner of its anchor. The first word picks above (start), level with (center), or below (end); the second picks the start side, the center, or the end side. Corner pairs such as start-start sit diagonally off the anchor. Omit it and the tooltip takes its position from your style configuration, which is end-center unless you have changed it.

Near the edge of the window the hint falls back to a placement that stays in view. Right-to-left text mirrors the start and end sides.

Anchoring⁠

By default the tooltip wraps its anchor. To describe an element that is already on the page, give the tooltip that element's id in anchor and leave its default slot empty. The tooltip then positions against the element where it sits.

An id resolves within one root node only. Pairing external-anchor with anchorElement reaches an element that an id cannot find; the API tab describes both.

Opening and closing⁠

Hover and focus open the hint on their own: a pointer opens it after a 100 ms pause, and focus opens it at once. Leaving closes it after 300 ms for a pointer and 150 ms for focus, which leaves time to move onto the hint. Escape closes it at any moment.

Call show or hide to decide from code. Either one cancels a pending hover or focus timer first.

In a toolbar⁠

A row of icon buttons shows no labels, so each hint adds what the icon cannot say: the shortcut. Each button keeps its own aria-label as its name.

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 Anchoring.
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. See Anchoring.
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 Anchoring.
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.

position states a preference: near the edge of the window the tooltip falls back to a placement that keeps it in view. An anchor id that matches no element in the root node logs a warning, and the tooltip never shows.

Slots⁠

SlotDescription
(default)The anchor element. Not used, and not rendered, when anchor or external-anchor supplies the anchor.
contentThe text the tooltip shows.

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 Anchoring.
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. See Anchoring.
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 Anchoring.
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.

position states a preference: near the edge of the window the tooltip falls back to a placement that keeps it in view. An anchor id that matches no element in the root node logs a warning, and the tooltip never shows.

Children⁠

ChildDescription
childrenThe anchor element. Not used, and not rendered, when anchor or externalAnchor supplies the anchor.
a child with slot="content"The text the tooltip shows.

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 Anchoring.
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. See Anchoring.
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 Anchoring.
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.

position states a preference: near the edge of the window the tooltip falls back to a placement that keeps it in view. An anchor id that matches no element in the root node logs a warning, and the tooltip never shows.

Render fragments⁠

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

<CbPlainTooltip>
    <Content>Content</Content>
    <ChildContent>Main content</ChildContent>
</CbPlainTooltip>
content_copy
ParameterTypeDescription
ChildContentRenderFragment?The anchor element. Not used, and not rendered, when Anchor or ExternalAnchor supplies the anchor.
ContentRenderFragment?The text the tooltip shows.

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 Anchoring.
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. See Anchoring.
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 Anchoring.
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.

position states a preference: near the edge of the window the tooltip falls back to a placement that keeps it in view. An anchor id that matches no element in the root node logs a warning, and the tooltip never shows.

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="content"The text the tooltip shows.

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 Anchoring.
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. See Anchoring.
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 Anchoring.
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.

position states a preference: near the edge of the window the tooltip falls back to a placement that keeps it in view. An anchor id that matches no element in the root node logs a warning, and the tooltip never shows.

Slots⁠

SlotDescription
defaultThe anchor element. Not used, and not rendered, when anchor or externalAnchor supplies the anchor.
contentThe text the tooltip shows.

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 Anchoring.
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. See Anchoring.
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 Anchoring.
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.

position states a preference: near the edge of the window the tooltip falls back to a placement that keeps it in view. An anchor id that matches no element in the root node logs a warning, and the tooltip never shows.

Snippets⁠

SnippetDescription
childrenThe anchor element. Not used, and not rendered, when anchor or externalAnchor supplies the anchor.
contentSnippetThe text the tooltip shows.

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-plain-tooltip-container-color--ct-sys-color-inverse-surface --ct-plain-tooltip-container-color
--ct-plain-tooltip-container-elevation0 --ct-plain-tooltip-container-elevation
--ct-plain-tooltip-outline-colortransparent --ct-plain-tooltip-outline-color
--ct-plain-tooltip-outline-opacity1 --ct-plain-tooltip-outline-opacity
--ct-plain-tooltip-outline-width0px --ct-plain-tooltip-outline-width
--ct-plain-tooltip-supporting-text-color--ct-sys-color-inverse-on-surface --ct-plain-tooltip-supporting-text-color
--ct-plain-tooltip-supporting-text-font--ct-sys-typescale-body-small-font --ct-plain-tooltip-supporting-text-font
--ct-plain-tooltip-supporting-text-line-height--ct-sys-typescale-body-small-line-height --ct-plain-tooltip-supporting-text-line-height
--ct-plain-tooltip-supporting-text-size--ct-sys-typescale-body-small-size --ct-plain-tooltip-supporting-text-size
--ct-plain-tooltip-supporting-text-tracking--ct-sys-typescale-body-small-tracking --ct-plain-tooltip-supporting-text-tracking
--ct-plain-tooltip-supporting-text-weight--ct-sys-typescale-body-small-weight --ct-plain-tooltip-supporting-text-weight

Names and states⁠

A screen reader announces the hint as a tooltip, as the WAI-ARIA Authoring Practices: Tooltip pattern describes.

  • The hint never names its anchor, so give the anchor its own text or aria-label.
  • A screen reader reads the hint after the anchor's name, as a description. A hint that only repeats the anchor's name is not read a second time. The description follows later edits to the hint's text and to the anchor's name.
  • Keep the tooltip in the same tree as its anchor, or in a tree that encloses it. From a tree the anchor is outside of, no reference reaches the text, and the tooltip logs a warning.
  • Anchor on a native control, or on a Chameleon control that takes a description, such as a button, a chip, a checkbox, or a switch. A Chameleon control that cannot take a description logs a warning, and its hint is not read.

Keyboard and focus⁠

Key Action
Tab Moves focus onto the anchor, which opens the hint, and off it, which closes the hint after 150 ms.
Escape Closes a visible hint, whether the pointer or focus opened it.

Tab is the browser's own behavior: the tooltip adds no tab stop, and its text is not focusable.

  • The hint opens on keyboard focus only when the anchor can take focus. Use a button, a link, or a field; a bare <span> opens it on hover alone.
  • The tooltip draws no focus ring of its own. The anchor shows its own focus indicator.
  • Focus moving from the anchor onto the hint keeps it open.

Pointer and touch⁠

The hint is not a target, so the tooltip sets no target size. The 24 by 24 pixel minimum of WCAG 2.5.8 applies to the anchor.

  • A pointer opens the hint after a 100 ms pause, and the hint stays open while the pointer is over the anchor or the hint.
  • Leaving the anchor closes the hint after 300 ms, which leaves time to cross the gap onto it.

Display settings⁠

  • Reduced motion: with a reduced-motion preference, the hint appears and disappears without its fade.
  • Right-to-left: the hint's text takes the direction of its context, and position mirrors as the Examples tab shows.

Standards⁠

With its defaults, the plain tooltip meets two WCAG 2.2 success criteria:

  • 1.3.1 Info and Relationships (A)
  • 1.4.13 Content on Hover or Focus (AA)

Two more depend on how you use it:

  • 2.1.1 Keyboard (A): anchor on a control that takes keyboard focus.
  • 2.5.8 Target Size (Minimum) (AA): size the anchor to at least 24 by 24 pixels.