Overview

<sp-tooltip> allow users to get contextual help or information about specific components when hovering or focusing on them.

Usage

yarn add @spectrum-web-components/tooltip

Import the side effectful registration of <sp-tooltip> via:

import '@spectrum-web-components/tooltip/sp-tooltip.js';

When looking to leverage the Tooltip base class as a type and/or for extension purposes, do so via:

import { Tooltip } from '@spectrum-web-components/tooltip';

Anatomy

The tooltip consists of several key parts:

• The message content in its default slot
• An optional icon using slot="icon"
• A tip element that points to the trigger

<sp-tooltip open>
  <sp-icon-info slot="icon"></sp-icon-info>
  Tooltip message
</sp-tooltip>

Options

Placement

Tooltips can be positioned relative to their trigger element using the placement attribute:

<sp-tooltip open placement="left">Left</sp-tooltip>
<sp-tooltip open placement="bottom">Bottom</sp-tooltip>
<sp-tooltip open placement="right">Right</sp-tooltip>
<sp-tooltip open placement="top">Top</sp-tooltip>

Variants

The tooltip supports several variants to convey different types of messages:

Use variant="info" for informational messages.

<sp-tooltip open placement="top" variant="info">
  <sp-icon-info slot="icon" size="s"></sp-icon-info>
  Embark on a side quest.
</sp-tooltip>

Use variant="positive" for success messages.

<sp-tooltip open placement="top" variant="positive">
  <sp-icon-checkmark-circle slot="icon" size="s"></sp-icon-checkmark-circle>
  Quest completed!
</sp-tooltip>

Use variant="negative" for error messages.

<sp-tooltip open placement="top" variant="negative">
  <sp-icon-alert slot="icon" size="s"></sp-icon-alert>
  Quest failed!
</sp-tooltip>

Behaviors

Overlay

By default, Tooltip provides styling without behavior.

You must combine it with an Overlay Trigger to manage its overlay behavior.

<overlay-trigger triggered-by="hover">
  <sp-button slot="trigger" variant="secondary">Hover me</sp-button>
  <sp-tooltip slot="hover-content" placement="bottom">
    Tooltip overlay triggered by hover
  </sp-tooltip>
</overlay-trigger>

For simpler use cases, you can use the self-managed attribute which automatically binds the Tooltip to its first interactive ancestor element's focus/hover interactions:

<sp-action-button>
  Items
  <sp-tooltip self-managed>Use items during battle.</sp-tooltip>
</sp-action-button>

This is especially useful when inserting an intermediate <overlay-trigger> would interfere with parent/child relationships, such as between <sp-action-group> and <sp-action-button>.

Delayed Opening

A tooltip can be configured to delay its opening using the delayed attribute. This adds a warm-up period of 1000ms before showing the tooltip:

<sp-action-button>
  Show delayed tooltip
  <sp-tooltip self-managed delayed>
    This tooltip will show after a delay
  </sp-tooltip>
</sp-action-button>

Accessibility

The tooltip is automatically assigned appropriate ARIA attributes:

• role="tooltip" is applied to the tooltip content
• The tooltip is associated with its trigger element via aria-describedby

When using self-managed tooltips:

• The tooltip appears on hover or focus of the trigger element
• The tooltip disappears when focus or hover leaves the trigger element
• Escape dismisses the tooltip

Use tooltips to describe icons

Icons are not always easy to identify on their own. When you use components that don’t have labels — for example, icon-only action buttons and tabs — make sure to use tooltips to provide context for the icons.

Given that tooltip is not focusable by itself, it would not show up during tab navigation. A tooltip should only be used with interactive elements that can receive focus during tab navigation, such as:

• <sp-action-button>
• <sp-action-menu>
• <sp-field-label>

For non-interactive elements like icons, wrap them in an interactive element:

<sp-action-button size="s">
  <sp-icon-book slot="icon"></sp-icon-book>
  <sp-tooltip self-managed placement="right">Save progress.</sp-tooltip>
</sp-action-button>

Use plain text in your tooltips

Because a tooltip is not focusable by itself, it should not contain any interactive elements. Additionally, because a tooltip is referenced in an aria-describedby attribute, it should not contain any rich formatting, such as headings, lists, bold, italic, or other complex content.

Don't use tooltips to communicate crucial information

Show crucial information at all times, not just when a tooltip is displayed. A tooltip should only be used to provide supplementary context or hints to the message shown in help text.

For example, in a scenario where a user is entering their password into a field, the crucial information would be to state the password requirements. Supplementary context would be a message about how to get help if they have forgotten their password.