@spectrum-web-components/tooltip

Overview

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

$3


``bash
yarn add @spectrum-web-components/tooltip
`

Import the side effectful registration of via:

`javascript
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:

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

$3

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

`html


Tooltip message

`

$3

#### Placement

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

`html
Left
Bottom
Right
Top
`

#### Variants

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


Info


Use variant="info" for informational messages.

`html


Embark on a side quest.

`


Positive


Use variant="positive" for success messages.

`html


Quest completed!

`


Negative


Use variant="negative" for error messages.

`html


Quest failed!

`

$3

#### Overlay

By default, Tooltip provides styling without behavior.


Overlay Trigger


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

`html

Hover me

Tooltip overlay triggered by hover


`


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:

`html

Items
Use items during battle.

`

This is especially useful when inserting an intermediate would interfere with parent/child relationships, such as between and .

#### 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:

`html

Show delayed tooltip

This tooltip will show after a delay


`

$3

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:

-
-
-

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

`html


Save progress.

`

#### 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.