@spectrum-web-components/tooltip

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:

Info

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>

Positive

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>

Negative

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.

Overlay Trigger

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>

Self-managed

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.

Changelog

1.7.0 (2025-06-11)

Minor Changes

sp-overlay: Fixed : Overlays (like pickers and action menus) were incorrectly closing when scrolling occurred within components. The fix ensures the handleScroll method in OverlayStack only responds to document/body scrolling events and ignores component-level scrolling events, which was the original intention.

sp-card: Fixed: On mobile Chrome (both Android and iOS), scrolling on sp-card components would inadvertently trigger click events. This was caused by the timing-based click detection (200ms threshold) in the pointer event handling, which could misinterpret quick scrolls as clicks. This issue did not affect Safari on mobile devices.

sp-action-button: - Fixed : Action buttons with href attributes now properly detects modifier keys and skips the proxy click, allowing only native browser behavior to proceed.

Patch Changes

sp-styles: Remove unnecessary system theme references to reduce complexity for components that don't need the additional mapping layer.

sp-card: - Fixed: sp-card component relies on sp-popover for certain toggle interactive behaviors, but this dependency was missing from its dependency tree.

sp-menu: Fixes: Icons in menu stories weren't properly responding to theme changes when used in functional story components. Switching to class-based LitElement components ensures proper component lifecycle hooks and shadow DOM context for icon initialization and theme integration.

sp-tabs: Added @spectrum-web-components/action-button as a dependency for Tabs as its used in the direction button.

sp-split-view: Added @spectrum-web-components/shared dependency in splitview since it uses ranDomId from the shared package

sp-textfield: Replace deprecated word-break: break-word with overflow-wrap: break-word to align with modern CSS standards and improve cross-browser compatibility. This property was deprecated in Chrome 44 (July 2015) in favor of the standardized overflow-wrap property.