Tooltip
Tooltip is a floating text label that succinctly describes the function of an interactive element, typically Icon Button. It’s displayed continuously as long as the user hovers over or focuses on the element.
Props
Usage guidelines
- Providing helpful, but non-essential context to a UI element.
- Enhancing a baseline understanding of an element or feature.
- Using a separate Tooltip instance with IconButton. Use IconButton's built-in tooltip instead.
- Displaying information that is critical to the understanding of an element/feature. Use inline text instead.
- Offering context at the surface-level scope. Consider a Callout instead.
Best practices
Use Tooltip to describe the function of an interactive element, typically Icon Button, in as few words as possible.
Use Tooltip to restate text already visible on screen.
Use Tooltip to distinguish related actions with visually similar iconography.
Use Tooltip to communicate critical information, such as an error, instructions for performing a task or interaction feedback.
Use Tooltip to add supplementary information about a feature, typically paired with an info-circle
IconButton.
Accessibility
Labels
When using Tooltip with IconButton, avoid repetitive labeling. The accessibilityLabel
provided to IconButton should describe the intent of the button, not the icon itself. For instance, use “Settings” instead of “Cog icon”. Tooltip text
should expand upon that intention, as seen in the "cog" example below. If Tooltip text
is the same as IconButton accessibilityLabel
, then add accessibilityLabel=""
to the Tooltip, as seen with the "share" example below
Disabled elements
Tooltips must be paired with an interactive, focusable element, like Button or IconButton. They cannot be paired with anything disabled or static, because this prevents keyboard users from triggering Tooltip and consuming its content. To test if you’re using Tooltip properly, use your keyboard rather than your mouse to trigger Tooltip.
If you need to explain why an item is disabled, consider adding plain Text near the disabled item, or an info-circle
IconButton adjacent to the disabled element.
Localization
Be sure to localize the text
and accessibilityLabel
props. Note that localization can lengthen text by 20 to 30 percent.
Variants
Ideal direction
Pass in idealDirection
to specify the preferred position of Tooltip relative to its anchor element. The default direction is "down", which should be used in most cases. The actual position may change given the available space around the anchor element.
Inline
Use inline to properly position Tooltip relative to an inline element, such as an Icon Button
Link
Pass in link
to display a link at the bottom of Tooltip.
⚠️ Note: this feature will soon be deprecated, as it is not accessible. Please do not use it in new designs or features.
Z-index
Tooltip has Layer built in, allowing it to overlay surrounding content. Use zIndex
to specify the stacking order of Tooltip along the z-axis in the current stacking context. The example below shows FixedZIndex used in Modal and CompositeZIndex to layer Tooltip on top.
Within scrolling containers
ScrollBoundaryContainer is needed for proper positioning when Tooltip is anchored to an element that is located within a scrolling container. The use of ScrollBoundaryContainer ensures Tooltip remains attached to its anchor when scrolling.
Writing
- Describe only the element that triggers Tooltip.
- Focus on the action by beginning with a verb.
- Use succinct and scannable language.
- As much as possible, limit Tooltip's text to a maximum of 60 to 75 characters.
- Use sentence case while always capitalizing the word “Pin.”
- Describe elements other than the one that triggers Tooltip.
- Use Tooltip to restate text already visible on screen.
- Use Tooltip to communicate critical information, such as an error, instructions for performing a task, or interaction feedback.
Component quality checklist
Quality item | Status | Status description |
---|---|---|
Figma Library | Partially ready | Component is live in Figma, however may not be available for all platforms. |
Responsive Web | Ready | Component is available in code for web and mobile web. |
iOS | Component is not currently available in code for iOS. | |
Android | Component is not currently available in code for Android. |
Related
Popover
Popover displays a lightweight task related to the content on screen. One example of Popover is the board picker, which allows people to choose the board to save a Pin to. While Tooltips are purely text-based, Popovers offer broader content options, such as Buttons and Images.
ScrollBoundaryContainer
ScrollBoundaryContainer is needed for proper positioning when Tooltip is anchored to an element that is located within a scrolling container. The use of ScrollBoundaryContainer ensures Tooltip remains attached to its anchor when scrolling. See the within scrolling containers variant to learn more.
Toast
Toast provides feedback on an interaction. One example of Toast is the confirmation that appears when a Pin has been saved. Toasts appear at the bottom of a desktop screen or top of a mobile screen, instead of being attached to any particular element on the interface.