# Tooltip (w-tooltip)

## Description

A tooltip is a message box that is displayed when a user hovers over or gives focus to a UI element.

Tooltips should be used sparingly and contain succinct, supplementary information.

## Usage

A tooltip is a message box that is displayed when a user hovers over or gives focus to a UI element.

Tooltips should be used sparingly and contain succinct, supplementary information.

```html
<w-button id="my-button" aria-labelledby="my-tooltip">Hover over me</w-button>
<w-tooltip id="my-tooltip" for="my-button">I am a tooltip</w-tooltip>
```

## Accessibility

### ARIA attribute

We use `aria-labelledby` instead of `aria-describedby` to create the relationship between the tooltip and its target.

The ARIA Authoring Practices Guide (APG) recommends `aria-describedby`, but at time of writing that must be set directly on the focusable element. Since `w-button`'s focusable `button` element is inside a shadow root we can't set up that relationship. Cross-root references by ID is impossible and the related ARIA properties on the `Element` are read only.

We might revisit this design later should cross-root ARIA references become supported.

## Examples

By default the tooltip is placed above the target element if there is room. If there's no room above it flips side and is placed below the target.

<elements-example>
  
```html
<w-button id="basic-button" aria-labelledby="basic-tooltip">Hover over me</w-button>
<w-tooltip id="basic-tooltip" for="basic-button">I am a tooltip</w-tooltip>
```

</elements-example>

### Adjust placement

You can specify a different initial placement. If there's no room the tooltip flips to the opposite side of the target.

Available positions:

- `top` (this is the default)
- `bottom`
- `left`
- `right`

<elements-example>
  
```html
<w-button id="placed-button" aria-labelledby="placed-tooltip">Hover over me</w-button>
<w-tooltip id="placed-tooltip" for="placed-button" placement="right">I am a tooltip</w-tooltip>
```

</elements-example>

## Styling API

This component supports styling through **component tokens** (CSS custom properties with a --w-c- prefix) and **parts**.

### Parts

Use `::part(...)` from outside the component.

- `tooltip` - the tooltip container with background color, padding etc.
- `arrow` - a square container used for positioning the visual part of the arrow
- `beak` - the visual part of the arrow pointing at the target
- `hover-bridge` - an invisible element there to ensure the tooltip doesn't close when moving the cursor from the target to the tooltip

Example:

```css
w-tooltip::part(tooltip) {
  text-transform: uppercase;
}
```

### Component tokens

Set these on `w-tooltip` to override visuals.

```css
w-tooltip {
    --w-c-tooltip-bg: lime;
    --w-c-tooltip-color: black;
}
```

#### Layout & typography

- `--w-c-tooltip-z-index`

#### Background

- `--w-c-tooltip-bg`

#### Text color

- `--w-c-tooltip-color`

##### Shadow

- `--w-c-tooltip-box-shadow`

## `<w-tooltip>` API

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

### Properties

| Name | Type | Default | Summary |
|-|-|-|-|
| for | `string` | `""` | ID of the element that triggers the tooltip on hover or focus. |
| hide (JS only) | `hide() => void` | `-` | - |
| hide-delay | `number` | `0` | Milliseconds to wait before hiding the tooltip on mouseout. |
| no-arrow | `boolean` | `false` | Hide the arrow pointing toward the tooltip target. |
| open | `boolean` | `false` | Indicates whether the tooltip is visible or not. |
| placement | [`TooltipPlacement`](#tooltipplacement) | `"top"` | Sets the placement of the tooltip relative to its target. |
| show (JS only) | `show() => void` | `-` | - |
| show-delay | `number` | `150` | Milliseconds to wait before showing the tooltip on hover. |

### Property Details

#### for

ID of the element that triggers the tooltip on hover or focus.

- Type: `string`
- Default: `""`

#### hide (JS only)



- Type: `hide() => void`
- Default: `-`

#### hide-delay

Milliseconds to wait before hiding the tooltip on mouseout.

- Type: `number`
- Default: `0`

#### no-arrow

Hide the arrow pointing toward the tooltip target.

- Type: `boolean`
- Default: `false`

#### open

Indicates whether the tooltip is visible or not.

- Type: `boolean`
- Default: `false`

#### placement

Sets the placement of the tooltip relative to its target.

The tooltip will try to position itself at the given placement. If there is no room it will flip to the opposite side automatically.

- Type: [`TooltipPlacement`](#tooltipplacement)
- Default: `"top"`

#### show (JS only)



- Type: `show() => void`
- Default: `-`

#### show-delay

Milliseconds to wait before showing the tooltip on hover.

Keep at a non-zero value to avoid flickering the tooltip on and off when cursors move quickly past the target element.

Focusing the target element shows the tooltip immediately.

- Type: `number`
- Default: `150`

### Types

#### TooltipPlacement

`'top' | 'bottom' | 'left' | 'right'`