Tooltips

Tooltips display informative text when users hover over, focus on, or tap an element.

Android Not available Web Flutter iOS Not available

Usage

When activated, tooltips display a text label identifying an element, such as a description of its function.

Principles

Transient

Tooltips appear on hover, focus, or touch, and disappear after a short duration.

Paired

Tooltips are always paired nearby the element with which they are associated.

Succinct

Tooltips only include short, descriptive text.


Placement

DoUse tooltips for interactive imagery.

200% zoom
1. On hover
2. On focus
Don'tDon’t use tooltips to restate visible UI text.

200% zoom
1. On hover
2. On focus
Do200% zoom

1. Tooltips describe differences between similar elements
2. Tooltips distinguish actions with related iconography
Don't200% zoom

1. Don’t display shadows on tooltips
2. Don’t display rich information and imagery on tooltips
DoKeep the position of the tooltip visible.
Don'tDon’t crop tooltips.

Desktop

Desktop tooltip on hover

Mobile

Tooltip displayed through long press
Tooltip summoned through focus (Android only)

Behavior

A tooltip is displayed upon tapping and holding a screen element or component (on mobile) or hovering over it (desktop). Continuously display the tooltip as long as the user long-presses or hovers over the element.

Timing

Display the tooltip for 1.5 seconds. If the user takes another action before that time ends, the tooltip will disappear.

Transitions

Tooltips use a fade transition pattern to enter and exit the screen.

1. 200%
2. 100%

On desktop, tooltips appear in the center of click targets and stay in place while cursor moves within the target.

1. Tooltip disappears when cursor moves out of the touch target
2. Tooltip remains while cursor moves within the touch target


Theming

Reply Material Theme

This email app’s tooltips have been customized using Material Theming. Areas of customization include color, typography, and shape. Reply is an email app that uses...

This email app’s tooltips have been customized using Material Theming. Areas of customization include color, typography, and shape.

Reply’s customized tooltip.

Color

Reply’s tooltips use custom color on two elements: the container, and text string.

Element Category Attribute Value
Container On Surface Color
Opacity
#232F34
100%
Text string Surface Color
Opacity
#FFFFFF
100%

Typography

Reply’s tooltips use custom typography for the text string.

Element Category Attribute Value
Text string Caption Typeface
Font
Size
Case
Work Sans
Regular
12
Sentence case

Shape

Reply’s tooltips use a custom container shape, with a 50% corner radius.

Element Category Attribute Value
Container Small component Family
Size
Rounded
50%

Specs

Desktop

10dp #ffffff #616161e6 R97 G97 B97 A0.90 All corners Rounded: 4dp All measurements are displayed in device-independent pixels (dps)

  • Measurement C
  • Measurement 8
  • Measurement 8
  • Measurement 24
 

Mobile

14dp #ffffff #616161e6 R97 G97 B97 A0.90 All corners Rounded: 4dp All measurements are displayed in device-independent pixels (dps)

  • Measurement 32
  • Measurement 16
  • Measurement 16
  • Measurement C
 
No Android implementation guidance available

Using tooltips

Plain tooltips, when activated, display a text label identifying an element, such as a description of its function. Tooltips should include only short, descriptive text and avoid restating visible UI text.

Common use cases include:

  • Displaying full text that has been truncated
  • Identifying a UI affordance
  • Describing differences between similar elements
  • Distinguishing actions with related iconography

Rich tooltips provide greater context and assistance for taking action through the additions of an optional title and buttons.

Common use cases include:

  • Guidance on a particular section of the page or object
  • Providing informative and contextual actions

Installing tooltips

Styles

JavaScript instantiation

See Importing the JS component for more information on how to import JavaScript.

Making tooltips accessible

Each tooltip element placed into the DOM is expected to have a unique id. Their corresponding anchor element must be labeled with the aria-describedby attribute, establishing a relationship between the two elements.

Anchor elements for rich tooltips without interactive contents (a link or an action button), are similarly labeled with aria-describedby. Rich tooltips without interactive content also have the aria-role tooltip.

Anchor elements for rich tooltips with interactive elements are labeled with data-tooltip-id. This prevents the screen reader from announcing the contents prior to the user navigating into the tooltip, and giving focus to the interactive elements. Rich tooltips with interactive content have the aria-role dialog instead of tooltip and their anchor elements has their aria-haspopup property set to dialog, and aria-expanded set to the visibility of the interactive rich tooltip.

Tooltips

There are two types of tooltips:

  1. Plain Tooltips
  2. Rich Tooltips

Plain tooltips

Plain tooltip example

Plain tooltip example

To ensure proper positioning of the tooltip, it's important that this tooltip element is an immediate child of the <body>, rather than nested underneath the anchor element or other elements.

The aria-describedby attribute (which is given the id for the associated tooltip) designates an element as being the anchor element for a particular tooltip.

Other MDC components can be designated as anchor elements by adding this attribute.

Rich tooltips

Rich tooltip example

Rich tooltips have two variants: default and persistent.

Default rich tooltips are shown when users hover over or focus on their anchor element. They remain shown when users focus/hover over the contents of the rich tooltip, but becomes hidden if the users focus/hover outside of the anchor element or the tooltip contents. If the user clicks within the contents of the tooltip, the tooltip will also be hidden.

Persistent rich tooltips' visibility is toggled by clicks and enter/space bar keystrokes on their anchor element. When shown, they remain visible when users focus/hover over the contents of the rich tooltip, as well as when users hover outside of the anchor element or the tooltip contents. However, they become hidden when the users focus outside of the anchor element or the tooltip contents. If the user clicks within the contents of the tooltip, the tooltip remains shown. If the user clicks outside the contents of the tooltip, the tooltip will be hidden. It is recommended that persistent rich tooltips are not added to anchor elements that already have an click action; the click action for the anchor element should be used solely to toggle the visibility of the rich tooltip.

Rich tooltip example

Default rich tooltip without interactive content

The rich tooltip element should be a sibling of the anchor element; the anchor and the tooltip element should be wrapped in a parent div with the class mdc-tooltip-wrapper--rich or the tooltip will not be positioned correctly.

Default rich tooltip with interactive content

Note that any links used within the rich tooltip has the class mdc-tooltip__content-link. This is to ensure that the color of links within rich tooltips are consistent with the color theming.

Persistent rich tooltip with interactive content

Note that persistent rich tooltips have tabindex set to -1. This is added to ensure that the tooltip is not hidden when clicked on.

MDC Button:

MDC Icon Button:

If the information provided in the tooltip is duplicated from the anchor element's aria-label, the tooltip can be hidden from the screenreader by annotating the anchor element with data-tooltip-id instead of aria-describedby, and adding a data-hide-tooltip-from-screenreader="true" attribute. Hiding the tooltip from the screenreader will prevent the same information from being announced twice (once from the aria-label and a second time from the tooltip).

Tooltip positioning

Tooltip positioning is based on the anchor element.

Plain tooltips appear directly below or above this anchor element and can be placed flush with either the end, center, or start of the anchor.

End, center, and start alignment of tooltip on icon button in a LTR page

*Plain tooltip aligned with the end, center, and start of an anchor element (in a LTR page flow).*

Rich tooltips appear directly below or above this anchor element, and can be placed at the corner of either the end or start of the anchor.

End and start alignment of rich tooltip on button in a LTR page

*Rich tooltip aligned with the end and start of an anchor element (in a LTR page flow).*

A threshold distance of 32px is expected to be maintained between the tooltip and the viewport edge. A valid tooltip position is calculated based on which of the position options (start, center, or end for x-axis alignment and above or below for y-axis alignment) maintain this threshold. If all possible alignment options violate the threshold, then a valid tooltip position is one that does not collide with the viewport.

A user specified position is honored only if the specified position is considered valid based on the logic outlined above.

API

Sass mixins

Access to theme mixins require importing the tooltip's theme style module.

MixinDescription
fill-color($color)Sets the fill color of the tooltip.
rich-fill-color($color)Sets the fill color of the rich tooltip.
label-ink-color($color)Sets the color of the tooltip's label text.
rich-text-ink-color($title-color, $content-color, $content-link-color)Sets the color of the text for the content inside a rich tooltip.
shape-radius($radius, $rtl-reflexive)Sets the rounded shape to tooltip surface with given radius size. Set $rtl-reflexive to true to flip radius values in RTL context, defaults to false.
word-break($value, $fallbackValue)Sets the word-break property for the tooltip label. This is used to force-wrap long tooltip labels that lack spaces and hyphens. The optional $fallbackValue param can be used for IE11 as it does not support the break-word option. Users for IE11 who do not want their tooltip labels to be broken in the middle of the word can use this mixin to remove the default IE11 behavior of break-all.
z-index($z-index)Sets the z-index of the tooltip.
show-transition($enter-duration)Sets the duration for the animation that shows the tooltip.
exit-transition($exit-duration)Sets the duration for the animation that hides the tooltip.

MDCTooltip Methods

Method SignatureDescription
setTooltipPosition(position: {xPos?: XPosition, yPos?: YPosition}) => voidSpecify how the tooltip should be aligned with the anchor element. See tooltip positioning section for more information.
setAnchorBoundaryType(type: AnchorBoundaryType) => voidSpecify whether the anchor element is bounded (element has an identifiable boundary such as a button) or unbounded (element does not have a visually declared boundary such as a text link). Tooltips are placed closer to bounded anchor elements compared to unbounded anchor elements. If no type is specified, defaults to bounded.
hide() => voidProxies to the foundation's hide method, immediately hides the tooltip if it is shown.
isShown() => booleanReturns whether or not the tooltip is shown.
attachScrollHandler(addEventListenerFn: (event, handler) => void)Provided with a method that registers an event listener on a given element, will attach a scroll event handler on said element when the tooltip is shown. This should be used in situations where the anchor element is placed inside a scrollable container (that is not the body element), and will keep the tooltip "attached" to the anchor element when this element is scrolled.
removeScrollHandler(removeEventHandlerFn: (event, handler) => void)Should be used in conjunction with the above attachScrollHandler method. Removes the additional scroll handlers attached in the above method when the tooltip is hidden.
setShowDelay(delayMs: number) => voidSpecify the delay prior to a tooltip being shown.
setHideDelay(delayMs: number) => voidSpecify the delay prior to a tooltip being hidden.

Usage Within Frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a Tooltip for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.

See MDCTooltipAdapter and MDCTooltipFoundation for up-to-date code documentation of tooltip foundation APIs.

No Web implementation guidance available

Using tooltips

When activated, tooltips display a text label identifying an element, such as a description of its function.

Making tooltips accessible

Screen readers will read the message property of the Tooltip. Adding tooltips is also a good way to make other Widgets in your app more accessible.

Key properties for tooltips

A tooltip has text label and a container.

  1. Text label
  2. Container

Text label for tooltip

 Property
Text labelmessage of Tooltip
Colorcolor of textStyle of Tooltip
TypographytextStyle of Tooltip

Container for tooltip

 Property
Colorcolor of decoration of Tooltip
Shapeshape of decoration of Tooltip

Tooltips example

Tooltip

Tooltip for 'Play' icon with rounded corner shape, white text, and dark grey background

Theming tooltips

Tooltips support Material Theming and can be customized in terms of color, typography, and shape.

To change the background color and shape, use the decoration property. To change the text typography, color, etc, use the textStyle property.

Tooltip

The following example shows a play icon and tooltip using Material's Reply theme.

Tooltip for 'Play' icon with pill shape, white text and blue-grey background

No Flutter implementation guidance available
No iOS implementation guidance available

Up next