Tooltip

Anatomy

1. Container: A rectangular frame that holds the tooltip text.
2. Text: A description of what the element is in which the mouse pointer is hovering over.

Usage Guidance

• Tooltips provide relevant and descriptive information about an element.
• They appear when a user hovers over or interacts with the related element.
• Tooltip text should be descriptive, yet short and succinct.
• Tooltips should always be positioned next to the element it is connected to. The Tooltip’s position will vary depending on where the element is in relation to the edge of the screen.

When to Use

• Use Tooltips to help users differentiate between similar elements.
• Pair Tooltips with icon only Primary/Secondary/Tertiary Buttons variants to help communicate the meaning or purpose of the icon.

Examples

This component follows the W3 Tooltip specification. Tooltips are used to label buttons with icons and provide additional context to elements.

When to use tooltips

Use a tooltip when you want to display additional information for users to better understand the purpose, context, or interaction.

When not to use tooltips

When the visual text will be the exact same as what is visually displayed to the user without the tooltip being visible

• Does this element need additional context or information?
  • No: Don't use a tooltip
  • Yes:
    • Is the tooltip text useful to screen reader users?
      • No: Use type="muted" which will not make the tooltip visible to screen reader users
      • Yes:
        • Is the tooltip text different from the visual text displayed to users?
          • No text: Use type="label" which will add aria-label like the icon example
          • Yes: Use type="describe" which will add aria-describedby
          • No: Don't use a tooltip

Basic Example

Here is a basic example of a TertiaryButton that renders an icon using a tooltip to label the icon. This labels the button for both sighted users and screen readers. A tooltip provides an aria-label to child elements for the accessibility tree and a visual tooltip during mouse hover and focus events.

Describing an Element

The default mode for a tooltip is to label content via aria-label. If a tooltip is meant to provide ancillary information, the type can be set to describe. This will add aria-describedby to the target element. This will allow screen reader users to hear the name of the control that is being focused and the ancillary tooltip information.

Muted Tooltips

If a tooltip does not need to be visible to screen reader users, or you handle accessibility of the tooltip yourself, you can set the type to muted. This will not add any special ARIA attributes to the target element.

Custom Content

A tooltip can contain HTML, but should not contain any focusable elements or semantically meaningful formatting. The content will lose all semantic meaning when read by a screen reader. If complex content or a focusable element is needed by your UI, a tooltip is not a good choice. Consider using a dialog instead.

Delayed Tooltip

The default delay for showing and hiding a tooltip are 300ms and 100ms, respectively. You can control the length of the delay by providing custom showDelay and hideDelay in ms.

Placements

The tooltip allows for a placement configuration. The tooltip uses PopperJS to position tooltips, so any valid PopperJS placement is valid for tooltips.

Tooltips on overflowing content

The OverflowTooltip component can be applied to any element that has some type of overflow applied, or has a child element that has overflow applied. The most common and widely supported type of truncation is the ellipsis.

overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;

Note: Text truncation should be avoided if possible. A user should not have to activate a tooltip to access important content. If user-generated content is being truncated, the following situation might occur which is a bad user experience. Consider the following list:

• Home Site A
• Home Site B
• Home Site C

If the list items get truncated via an ellipsis, this is what the user could see:

• Home Sit...
• Home Sit...
• Home Sit...

Here are suggestions to try to avoid truncation:

• Allow content to wrap instead
• Limit character count in admin interfaces if possible to avoid need for truncation
• Avoid fixed container sizes if possible to allow content to flow naturally

If truncation is required, here are a few guidelines to insure minimal impact on users:

• Only truncate text of elements that naturally receive focus.
  • Keyboard users can only activate tooltips with focus. Adding tabindex=0 can give focus to non-focusable elements, but increase the amount of tab stops for keyboard users.
• Provide the full content elsewhere in the UI

Canvas Kit Buttons have this style applied to the text inside them. OverflowTooltip in combination with a max-width can show a tooltip only when overflow is detected:

Line Clamp

The OverflowTooltip can support various types of overflow. The component will first look for text-overflow: ellipsis and -webkit-line-clamp, but will fall back to overflow: auto | scroll | clip | hidden. These properties will be used to determine which element is experiencing an overflow. Overflow detection is as follows where element is determined by the above style properties:

element.scrollWidth > element.clientWidth || element.scrollHeight > element.clientHeight;

Here's an example using the -webkit-line-clamp property (multi-line ellipsis which works in all browsers):

Other truncation techniques should be supported as well, even JavaScript ones as long as overflow is triggered somehow and detectable differences in scroll size and client size.

The UseTooltip Hook

The Tooltip component is a combination of the TooltipContainer (a styled element), Popper (which uses PopperJS and the popup stack), the useTooltip hook and some behavior. If custom behavior is required, these sub-components can be composed in a custom container element. This example uses those parts directly while being functionally equivalent to the original basic example.

Component API

Specifications

Accessibility Guidelines

How Tooltips Impact the Accessible Experience

Tooltip “hover” text is a great way to help users understand the intent of ambiguous icons, and provide further detail about some elements in a design. A hovering interaction however, is not going to be available to all users at all times. Mobile devices don’t support hovering interactions, and desktop users may not be willing or able to use a pointing device to hover on an element.

Alternatives to the hover interaction must be considered, and tooltip content must be displayed visually on keyboard focus. Tooltips can be used for showing truncated text, but only in scenarios where the keyboard can focus the component. Applying tooltips to truncated heading or paragraph text will lead to accessibility problems.

Refer to tooltips and toasts for more information about writing tooltip content.

Keyboard Interaction

Tooltips must only be used on elements that can be focused with the keyboard. Sighted users must be able to access the content in a tooltip without the use of a mouse.

Tooltips must support the following keyboard interactions:

• Tab: focuses an element, tooltip displays when element is focused
• Esc: dismiss tooltip

Screen Reader Interaction

Tooltips must communicate the following to users:

• The text content of the tooltip as the name of an element (default)
• The text content of the tooltip as an element’s description (describe)
• Nothing, when the tooltip text content matches text content already on screen. (muted)

Design Annotations Needed

• Specify which tooltip variant should be used: default, describe, or muted.

Implementation Markup Needed

• [Included in component] Default tooltips will set an aria-label string to the element.
• [Included in component] Describe variant will instead set an aria-describedby attribute to the element, referencing an id of the tooltip text content.
• [Included in component] Muted variant will be hidden from screen readers and other assistive technology.

Content Guidelines

Keep tooltips brief. Tooltips should not text wrap or span more than a single line. Try to keep Tooltips understandable and clear for users by adding context to the element through simple combinations of nouns and verbs, such as “Add Item” over a Plus icon or “Close” over an X icon. For more information on writing Tooltip text, see the Tooltips and Toasts section of the content style guide.