adobeOverview
<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:
<sp-tabs selected="info" auto label="Variant Options">
<sp-tab value="info">Info</sp-tab>
<sp-tab-panel value="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>
</sp-tab-panel>
<sp-tab value="positive">Positive</sp-tab>
<sp-tab-panel value="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>
</sp-tab-panel>
<sp-tab value="negative">Negative</sp-tab>
<sp-tab-panel value="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>
</sp-tab-panel> </sp-tabs>
Behaviors
Overlay
By default, Tooltip provides styling without behavior.
<sp-tabs selected="overlay-trigger" auto label="Overlay Behaviors">
<sp-tab value="overlay-trigger">Overlay Trigger</sp-tab>
<sp-tab-panel value="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>
</sp-tab-panel>
<sp-tab value="self-managed">Self-managed</sp-tab>
<sp-tab-panel value="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>.
</sp-tab-panel> </sp-tabs>
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
- <kbd>Escape</kbd> 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.