sp-tooltip

NPM 1.6.0

View Storybook

Try it on Stackblitz
Overview API Changelog

Overview

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

Usage

See it on NPM! How big is this package in your project? Try it on Stackblitz

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.

Patch Changes

  • #5384 700489f Thanks @Rajdeepc! - docs: add DelayedTooltipWithOverlay story demonstrating how to handle interactions between delayed tooltips and other overlay components

  • #5349 a9727d2 Thanks @renovate! - Remove unnecessary system theme references to reduce complexity for components that don't need the additional mapping layer.

  • Updated dependencies [53f3769]:

    • @spectrum-web-components/overlay@1.6.0
    • @spectrum-web-components/base@1.6.0
    • @spectrum-web-components/reactive-controllers@1.6.0
    • @spectrum-web-components/shared@1.6.0

1.5.0

Patch Changes

  • Updated dependencies [8f8735c]:
    • @spectrum-web-components/overlay@1.5.0
    • @spectrum-web-components/base@1.5.0
    • @spectrum-web-components/reactive-controllers@1.5.0
    • @spectrum-web-components/shared@1.5.0

1.4.0

Patch Changes

  • Updated dependencies [46cd782, 70f5f6f]:
    • @spectrum-web-components/overlay@1.4.0
    • @spectrum-web-components/base@1.4.0
    • @spectrum-web-components/reactive-controllers@1.4.0
    • @spectrum-web-components/shared@1.4.0

1.3.0

Patch Changes

  • Updated dependencies [ea38ef0, 468314f]:
    • @spectrum-web-components/reactive-controllers@1.3.0
    • @spectrum-web-components/overlay@1.3.0
    • @spectrum-web-components/base@1.3.0
    • @spectrum-web-components/shared@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.2.0 (2025-02-27)

Note: Version bump only for package @spectrum-web-components/tooltip

1.1.2 (2025-02-12)

Bug Fixes

  • tooltip: make tooltip delivery consistent across all browsers (#5056) (d01d5cd)

1.1.1 (2025-01-29)

Note: Version bump only for package @spectrum-web-components/tooltip

1.1.0 (2025-01-29)

Bug Fixes

  • lock prerelease versions for Spectrum CSS (#5014) (8aa7734)

Features

  • add an optional chromatic vrt action (7d2f840)

1.0.3 (2024-12-09)

Note: Version bump only for package @spectrum-web-components/tooltip

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/tooltip

1.0.0 (2024-10-31)

Note: Version bump only for package @spectrum-web-components/tooltip

0.49.0 (2024-10-15)

Note: Version bump only for package @spectrum-web-components/tooltip

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/tooltip

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/tooltip

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/tooltip

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/tooltip

0.47.0 (2024-08-20)

Note: Version bump only for package @spectrum-web-components/tooltip

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/tooltip

0.45.0 (2024-07-30)

Note: Version bump only for package @spectrum-web-components/tooltip

0.44.0 (2024-07-15)

Bug Fixes

  • overlay: ensure hint Overlays within shadow roots open as expected (#4443) (7dd64b9)

0.43.0 (2024-06-11)

Bug Fixes

  • overlay: ensure hint Overlays within shadow roots open as expected (#4443) (7dd64b9)

0.42.5 (2024-05-24)

Bug Fixes

  • overlay: ensure hint Overlays within shadow roots open as expected (#4443) (7dd64b9)

0.42.4 (2024-05-14)

Bug Fixes

  • tooltip: fix infinite loop in self-managed tooltips (#4269) (b66ee49)

0.42.3 (2024-05-01)

Bug Fixes

  • tooltip: fix infinite loop in self-managed tooltips (#4269) (b66ee49)

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/tooltip

0.42.1 (2024-04-02)

Note: Version bump only for package @spectrum-web-components/tooltip

0.42.0 (2024-03-19)

Features

  • asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/tooltip

0.41.1 (2024-02-22)

Note: Version bump only for package @spectrum-web-components/tooltip

0.41.0 (2024-02-13)

Note: Version bump only for package @spectrum-web-components/tooltip

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/tooltip

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/tooltip

0.40.3 (2024-01-11)

Bug Fixes

  • overlay: move closed overlays to "display: none" (fc0278b)
  • picker: force close slotted Tooltip elements with disabled when Menu openes (82c8f12)
  • tooltip: surface "delayed" and "disabled" functionality (#3882) (ae9fcd2)

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/tooltip

0.40.1 (2023-12-05)

Note: Version bump only for package @spectrum-web-components/tooltip

0.40.0 (2023-11-16)

Note: Version bump only for package @spectrum-web-components/tooltip

0.39.4 (2023-11-02)

Note: Version bump only for package @spectrum-web-components/tooltip

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/tooltip

0.39.2 (2023-10-13)

Note: Version bump only for package @spectrum-web-components/tooltip

0.39.1 (2023-10-06)

Bug Fixes

  • progress-circle,toast,tooltip: ensure complete dependency graph (#3701) (a5dfada)

0.39.0 (2023-09-25)

Note: Version bump only for package @spectrum-web-components/tooltip

0.38.0 (2023-09-05)

Note: Version bump only for package @spectrum-web-components/tooltip

0.37.0 (2023-08-18)

Bug Fixes

  • address margin effected positioning (38c8cf2)

Features

  • tooltip: leverage Overlay v2 (346edac)

Performance Improvements

  • make lots of things lazy (b8fa3ad)

0.36.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/tooltip

0.35.0 (2023-07-31)

Note: Version bump only for package @spectrum-web-components/tooltip

0.34.0 (2023-07-11)

Note: Version bump only for package @spectrum-web-components/tooltip

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/tooltip

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/tooltip

0.32.0 (2023-06-01)

Note: Version bump only for package @spectrum-web-components/tooltip

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/tooltip

0.30.0 (2023-05-03)

Bug Fixes

  • allow ActiveOverlay to manage open state (a7c4cff)
  • correct @element jsDoc listing across library (c97a632)
  • include "type" in package.json, generate custom-elements.json (1a8d716)
  • include default export in the "exports" fields (f32407d)
  • include the "types" entry in package.json files (b432f59)
  • overlay: add overlay lifecycle methods to stack management (9361527)
  • overlay: allow overlay-trigger to declaratively open overlay content (194a44e)
  • position tip shapes for bi-directional delivery (35654de)
  • special case the possibility of leaving an overlay trigger by entering its overlay content (c32a075)
  • stop merging selectors in a way that alters the cascade (369388f)
  • tooltip: correct arrow orientation, remove popper-arrow-rotate (fcd6ea2)
  • tooltip: ensure delayed and self-managed tooltips do not disrupt the page layout (0f43b25)
  • tooltip: manage describedby attributes non-destructively (8443136)
  • update consumption of Spectrum CSS for latest version (ed2305b)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • update side effect listings (8160d3a)
  • update to latest spectrum-css packages (a5ca19f)
  • use icons without "size" values (3fc7c91)
  • use latest @spectrum-css/* versions (c35eb86)
  • use the "browsers" listing in postcss-preset-env (4eaf6a2)

Features

  • action-button: add action button pattern (03ac00a)
  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • icons-workflow: vend fully registered icon components (941f3a4)
  • include all Dev Mode files in side effects (f70817c)
  • leverage "exports" field in package.json (321abd7)
  • rework overlays to use popper (e17d1bb)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
  • tooltip: initial release (c1331c9)
  • tooltip: update spectrum css input (a946b1c)
  • update to Spectrum CSS v3.0.0 (e8b3d8f)
  • use @adobe/spectrum-css@2.15.1 (3918888)
  • use latest exports specification (a7ecf4b)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)
  • use imported TypeScript helpers instead of inlining them (cc2bd0a)

Reverts

  • Revert "chore: release new versions" (a6d655d)

0.11.17 (2023-04-24)

Note: Version bump only for package @spectrum-web-components/tooltip

0.11.16 (2023-04-05)

Note: Version bump only for package @spectrum-web-components/tooltip

0.11.15 (2023-03-22)

Note: Version bump only for package @spectrum-web-components/tooltip

0.11.14 (2023-03-08)

Note: Version bump only for package @spectrum-web-components/tooltip

0.11.13 (2023-02-13)

Note: Version bump only for package @spectrum-web-components/tooltip

0.11.12 (2023-02-08)

Note: Version bump only for package @spectrum-web-components/tooltip

0.11.11 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/tooltip

0.11.10 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/tooltip

0.11.9 (2022-12-08)

Note: Version bump only for package @spectrum-web-components/tooltip

0.11.8 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/tooltip

0.11.7 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/tooltip

0.11.6 (2022-10-28)

Note: Version bump only for package @spectrum-web-components/tooltip

0.11.5 (2022-10-17)

Note: Version bump only for package @spectrum-web-components/tooltip

0.11.4 (2022-10-10)

Note: Version bump only for package @spectrum-web-components/tooltip

0.11.3 (2022-09-15)

Bug Fixes

  • special case the possibility of leaving an overlay trigger by entering its overlay content (c32a075)

0.11.2 (2022-09-14)

Note: Version bump only for package @spectrum-web-components/tooltip

0.11.1 (2022-08-24)

Note: Version bump only for package @spectrum-web-components/tooltip

0.11.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.10.17 (2022-08-04)

Note: Version bump only for package @spectrum-web-components/tooltip

0.10.16 (2022-07-18)

Note: Version bump only for package @spectrum-web-components/tooltip

0.10.15 (2022-06-29)

Note: Version bump only for package @spectrum-web-components/tooltip

0.10.14 (2022-06-07)

Note: Version bump only for package @spectrum-web-components/tooltip

0.10.13 (2022-05-27)

Bug Fixes

  • update consumption of Spectrum CSS for latest version (ed2305b)

0.10.12 (2022-05-12)

Note: Version bump only for package @spectrum-web-components/tooltip

0.10.11 (2022-04-21)

Note: Version bump only for package @spectrum-web-components/tooltip

0.10.10 (2022-03-30)

Note: Version bump only for package @spectrum-web-components/tooltip

0.10.9 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/tooltip

0.10.8 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/tooltip

0.10.7 (2022-03-04)

Note: Version bump only for package @spectrum-web-components/tooltip

0.10.6 (2022-02-22)

Note: Version bump only for package @spectrum-web-components/tooltip

0.10.5 (2022-02-02)

Note: Version bump only for package @spectrum-web-components/tooltip

0.10.4 (2022-01-26)

Note: Version bump only for package @spectrum-web-components/tooltip

0.10.3 (2022-01-26)

Bug Fixes

  • tooltip: manage describedby attributes non-destructively (8443136)

0.10.2 (2022-01-07)

Note: Version bump only for package @spectrum-web-components/tooltip

0.10.1 (2021-12-13)

Bug Fixes

  • tooltip: ensure delayed and self-managed tooltips do not disrupt the page layout (0f43b25)

0.10.0 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/tooltip

0.9.1 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/tooltip

0.9.0 (2021-11-02)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.8.18 (2021-10-12)

Note: Version bump only for package @spectrum-web-components/tooltip

0.8.17 (2021-09-20)

Note: Version bump only for package @spectrum-web-components/tooltip

0.8.16 (2021-09-13)

Note: Version bump only for package @spectrum-web-components/tooltip

0.8.15 (2021-08-24)

Bug Fixes

  • correct @element jsDoc listing across library (c97a632)

0.8.14 (2021-08-17)

Note: Version bump only for package @spectrum-web-components/tooltip

0.8.13 (2021-08-03)

Note: Version bump only for package @spectrum-web-components/tooltip

0.8.12 (2021-07-22)

Note: Version bump only for package @spectrum-web-components/tooltip

0.8.11 (2021-07-01)

Note: Version bump only for package @spectrum-web-components/tooltip

0.8.10 (2021-06-16)

Note: Version bump only for package @spectrum-web-components/tooltip

0.8.9 (2021-06-07)

Note: Version bump only for package @spectrum-web-components/tooltip

0.8.8 (2021-05-24)

Bug Fixes

  • overlay: add overlay lifecycle methods to stack management (9361527)

0.8.7 (2021-05-12)

Note: Version bump only for package @spectrum-web-components/tooltip

0.8.6 (2021-04-15)

Note: Version bump only for package @spectrum-web-components/tooltip

0.8.5 (2021-04-09)

Note: Version bump only for package @spectrum-web-components/tooltip

0.8.4 (2021-03-29)

Note: Version bump only for package @spectrum-web-components/tooltip

0.8.3 (2021-03-22)

Note: Version bump only for package @spectrum-web-components/tooltip

0.8.2 (2021-03-22)

Bug Fixes

  • overlay: allow overlay-trigger to declaratively open overlay content (194a44e)

0.8.1 (2021-03-05)

Note: Version bump only for package @spectrum-web-components/tooltip

0.8.0 (2021-03-04)

Features

  • use latest exports specification (a7ecf4b)

0.7.3 (2021-02-11)

Bug Fixes

  • update to latest spectrum-css packages (a5ca19f)

0.7.2 (2021-02-02)

Note: Version bump only for package @spectrum-web-components/tooltip

0.7.1 (2021-01-28)

Bug Fixes

  • position tip shapes for bi-directional delivery (35654de)
  • tooltip: correct arrow orientation, remove popper-arrow-rotate (fcd6ea2)
  • allow ActiveOverlay to manage open state (a7c4cff)

0.7.0 (2021-01-21)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use icons without "size" values (3fc7c91)
  • use latest @spectrum-css/* versions (c35eb86)
  • use the "browsers" listing in postcss-preset-env (4eaf6a2)

Features

  • action-button: add action button pattern (03ac00a)
  • icons-workflow: vend fully registered icon components (941f3a4)
  • tooltip: update spectrum css input (a946b1c)

0.6.0 (2021-01-13)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use icons without "size" values (3fc7c91)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • action-button: add action button pattern (03ac00a)
  • icons-workflow: vend fully registered icon components (941f3a4)
  • tooltip: update spectrum css input (a946b1c)

0.5.4 (2020-10-12)

Note: Version bump only for package @spectrum-web-components/tooltip

0.5.3 (2020-10-12)

Bug Fixes

  • include default export in the "exports" fields (f32407d)

0.5.2 (2020-09-25)

Bug Fixes

  • update side effect listings (8160d3a)

0.5.1 (2020-09-15)

Note: Version bump only for package @spectrum-web-components/tooltip

0.5.0 (2020-08-31)

Features

  • update to Spectrum CSS v3.0.0 (e8b3d8f)

0.4.6 (2020-08-19)

Note: Version bump only for package @spectrum-web-components/tooltip

0.4.5 (2020-08-13)

Note: Version bump only for package @spectrum-web-components/tooltip

0.4.4 (2020-08-13)

Note: Version bump only for package @spectrum-web-components/tooltip

0.4.3 (2020-08-05)

Note: Version bump only for package @spectrum-web-components/tooltip

0.4.2 (2020-07-24)

Note: Version bump only for package @spectrum-web-components/tooltip

0.4.1 (2020-07-22)

Note: Version bump only for package @spectrum-web-components/tooltip

0.4.0 (2020-07-17)

Features

  • leverage "exports" field in package.json (321abd7)

0.3.10 (2020-06-08)

Note: Version bump only for package @spectrum-web-components/tooltip

0.3.9 (2020-05-08)

Note: Version bump only for package @spectrum-web-components/tooltip

0.3.8 (2020-05-08)

Note: Version bump only for package @spectrum-web-components/tooltip

0.3.7 (2020-04-16)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)

0.3.6 (2020-04-10)

Note: Version bump only for package @spectrum-web-components/tooltip

0.3.5 (2020-04-07)

Note: Version bump only for package @spectrum-web-components/tooltip

0.3.4 (2020-03-16)

Note: Version bump only for package @spectrum-web-components/tooltip

0.3.3 (2020-03-11)

Note: Version bump only for package @spectrum-web-components/tooltip

0.3.2 (2020-02-24)

Note: Version bump only for package @spectrum-web-components/tooltip

0.3.1 (2020-02-05)

Note: Version bump only for package @spectrum-web-components/tooltip

0.3.0 (2020-01-30)

Features

  • rework overlays to use popper (e17d1bb)

0.2.2 (2020-01-06)

Note: Version bump only for package @spectrum-web-components/tooltip

0.2.1 (2019-11-27)

Bug Fixes

  • include "type" in package.json, generate custom-elements.json (1a8d716)

0.2.0 (2019-11-19)

Features

  • use @adobe/spectrum-css@2.15.1 (3918888)

0.1.1 (2019-10-14)

Performance Improvements

  • use imported TypeScript helpers instead of inlining them (cc2bd0a)

0.1.0 (2019-10-03)

Features

  • tooltip: initial release (c1331c9)

Attributes and Properties

Property Attribute Type Default Description offset offset number 0 open open boolean false placement placement "top" | "top-start" | "top-end" | "right" | "right-start" | "right-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end" selfManaged self-managed boolean false Automatically bind to the parent element of the assigned `slot` or the parent element of the `sp-tooltip`. Without this, you must provide your own `overlay-trigger`. tipPadding tipPadding number | undefined variant variant string

Slots

Name Description icon the icon element appearing at the start of the label default slot the text label of the Tooltip

Events

Name Type Description undefined TransitionEvent