## 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!](https://img.shields.io/npm/v/@spectrum-web-components/tooltip?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/tooltip)
[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/tooltip?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/tooltip)
[![Try it on Stackblitz](https://img.shields.io/badge/Try%20it%20on-Stackblitz-blue?style=for-the-badge)](https://stackblitz.com/edit/vitejs-vite-cizgmpks)

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

Import the side effectful registration of `<sp-tooltip>` 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';
```

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

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

```html
<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.

```html
<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.

```html
<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.

```html
<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](https://opensource.adobe.com/spectrum-web-components/components/overlay-trigger/#%22hover%22-content-only) to manage its overlay behavior.

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

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

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

```html
<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.