Version 5.1.0

Tooltip

Tooltips allow users to get contextual help or information about specific components when hovering or focusing on them.

An example of a tooltip implemented into UI. Tooltip is being used to annotate the "Flip horizontal" action.

Anatomy#


Image illustrating through labels the component parts of a tooltip including its background and tip.

Options#


Example of neutral tooltip with label, Copy link.

Label#

All tooltips have labels. These allow users to get contextual help or information about specific items when hovering over or focusing on them.

Example of neutral tooltip. Gray background color. Label, Copy link.

Neutral variant#

By default, tooltips are the neutral variant. These are the most common because most tooltips are used to simply disclose additional information, without conveying a semantic meaning. The neutral variant never has an icon.

Example of tooltips in semantic colors: informative in blue, positive in green and negative in red.

Semantic variants#

Tooltips also come in semantic variants: informative (blue), positive (green), and negative (red). These use semantic colors.

Example of three tooltips that have icons that support the messaging. Tooltips express informative in blue with an information icon, positive in green with a checkmark and negative in red with an exclamation point.

Icon#

Three of the four tooltips (informative, positive, and negative) can have icons to support the message. These icons are predefined and cannot be customized. Unless the tooltips are being used for the exact same icons, semantic tooltips should always show the icon. This is essential for users with color blindness to discern message tone.

Example of tooltip with two lines of text wrapped at maximum width. Label, Text auto-resized in symbol instance.

Maximum width#

By default, the maximum width of a tooltip is size-2000. This can be customized to better fit your context.

Table of options#

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework.

PropertyValuesDefault Value
label
text
variant
neutral / informative / positive / negative
neutral
has icon
yes / no
If the neutral variant, there’s never an icon.
no
maximum width
number
size-2000

Behaviors#


Key example of two tooltips with text overflow. A Neutral tooltip with text "Text auto-resized in symbol instance" and a. informative tooltip with an icon and text  "Text auto-resized in symbol instance".

Text overflow#

When the label is too long for the available horizontal space, it wraps to form another line.

Example of an animated neutral tool tip that fades in and out with text, "Saving applies your new settings right away".

Animation#

A tooltip fades in and out when showing and hiding, and slides a short distance from the source to indicate its origin. The direction of the slide (left, right, top, bottom) depends on the placement of the tooltip. The animation attributes (duration, easing, offset) are the same whether it’s showing or hiding.

Example of an animated neutral tool tip that fades in and out with a delay with text over save button or question button, "Saving applies your new settings right away".

Immediate or delayed appearance#

Tooltips attached to help icons appear immediately. For conventional UI elements where a tooltip appearing immediately would be intrusive, delay appearance with a warmup period.

Example of an animated neutral tool tip that fades in and out with text, "Saving applies your new settings right away". Cursor hovers over the save button for an allotted time before the tooltip appears.

Warmup and cooldown#

The warmup period is a global timer that requires the cursor to remain on a UI element for the allotted time before a tooltip will appear. Once the period is complete, tooltips appear instantly on any hovered UI elements until the cursor is in an area that does not trigger a tooltip for the duration of the cooldown period.

Usage guidelines#


Use tooltips to describe icons#

Icons are not always easy to identify on their own. Use tooltips to provide simple explanations.

Key example showing the correct use of a tooltip. A cursor over a print icon with the tooltip that states Print.

Be concise#

Tooltips should be as concise as possible while remaining clear. Ideally, the copy should be one or two lines of text. If the copy is too long, look into using a different design.

Key example showing the correct use of a tooltip with a concise tooltip descriptor. A cursor over a warning icon with the tooltip that states required field.
Key example showing the incorrect use of a tooltip with a lengthy tooltip descriptor. A cursor over a warning icon with the tooltip that states "the email field is required. Your email will be used as an identifiant when we create your account and you will receive a confirmation email".

Don't communicate crucial information#

Crucial informatiom should be visible on the screen at all times, not just when a tooltip is displayed. A tooltip should only be used to provide extra helpful information and context.

Key example showing the incorrect use of a tooltip that provides crucial information in the tooltip descriptor. A cursor over an information icon with a tooltip that states "must contain at least 8 characters"..

Don't place actions inside a tooltip#

Tooltips appear only on hover or when receiving focus from the keyboard. Therefore, tooltips should not contain actions or links.

Key example showing the incorrect use of a tooltip that provides a link in the tooltip descriptor. A cursor over a warning icon with a tooltip that states "fail to connect to server. Visit our help center for more information". The text "visit our help center" is identified as a link.

Internationalization#


An example of an informative, positive and negative tooltip with a descriptor in Arabic to demonstrate right to left language in a tooltip.

RTL#

For RTL (right-to-left) languages, the layout of the tooltip is mirrored. The icon is placed on the right side of the text.

Keyboard interactions#


KEYINTERACTION
TabTabbing into an item that has a tooltip associated (e.g., an icon) shows the tooltip.
EscHides the tooltip.

Changelog#


DateNumberNotes
Aug 22, 20195.1.0
  • Added text overflow behavior
Apr 19, 20195.0.0
  • This component is now individually versioned (individual versions of existing components start at 5.0.0)
  • Added RTL (right-to-left) guidelines

Design checklist#


N/A

All interactive states

Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).

Multiple options

Includes relevant options (variant, style, size, orientation, optional iconography, decorations, selection, error state, etc.)

All color themes

Works properly across all four color themes (lightest, light, dark, darkest).

All platform scales

Includes a desktop scale (UWP, macOS, web desktop) and a mobile scale (iOS, Android, web mobile).

Defined behaviors

Includes guidelines for layout (wrapping, truncation, overflow), animation, interactions, etc.

Usage guidelines

Includes a list of dos and don’ts that highlight best practices and common mistakes.

Accessible contrast

Follows WCAG 2.0 standards for contrast (AA).

Internationalization guidelines

Works properly across various locales and includes guidelines for bi-directionality (RTL).

Keyboard interactions

Follows WCAG 2.0 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions.

Generated UI kit

Includes a downloadable XD file that has been generated by code and shows multiple variations, states, color themes, and scales.

Design tokens

All design attributes (color, typography, layout, animation, etc.) are included in Spectrum DNA.