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
Desktop
Mobile
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.
On desktop, tooltips appear in the center of click targets and stay in place while cursor moves within the target.
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.
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
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.
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.
xxxxxxxxxx
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 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
xxxxxxxxxx
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
xxxxxxxxxx
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
xxxxxxxxxx
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:
xxxxxxxxxx
MDC Icon Button:
xxxxxxxxxx
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).
xxxxxxxxxx
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.
*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.
*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.
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.
Specify 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() => void
Proxies to the foundation's hide method, immediately hides the tooltip if it is shown.
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.
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) => void
Specify the delay prior to a tooltip being shown.
setHideDelay(delayMs: number) => void
Specify 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.