# dds-tooltip



<!-- Auto Generated Below -->


## Overview

A tooltip is a short floating label that explains the element it is anchored to. It opens while a pointer is over the trigger or focus is inside it, and closes on `Esc`. It is a visual aid only: link the content to the trigger with `aria-describedby` so assistive technology announces it, and give a trigger that is not natively focusable `tabindex="0"`.

## Usage

### Tooltip

#### Basic

Put the element that shows the tooltip in the `trigger` slot and the tooltip content in the default slot. The tooltip opens while a pointer is over the trigger or focus is inside it, and closes when both have left or on `Esc`.

```html
<dds-tooltip>
  <dds-button slot="trigger">Save</dds-button>
  <span>Saves your current progress.</span>
</dds-tooltip>
```

#### Announce the content to assistive technology

A tooltip is a visual aid until you link its content to the trigger. The default slot stays in the light DOM beside the trigger, so give the content an `id` and point the trigger's `aria-describedby` at it. The component writes no attribute on its children, and a reference cannot cross into the shadow root, so this wiring is yours to add.

```html
<dds-tooltip>
  <dds-button slot="trigger" aria-describedby="save-tip">Save</dds-button>
  <span id="save-tip">Saves your current progress.</span>
</dds-tooltip>
```

#### Make the trigger focusable

Keyboard users open the tooltip by focusing the trigger. A `dds-button` is focusable already. For anything else, such as inline text, add `tabindex="0"` yourself; the component never adds one.

```html
<p>
  Hover over
  <dds-tooltip>
    <span slot="trigger" tabindex="0" aria-describedby="total-sales-tip"
      >total sales</span
    >
    <span id="total-sales-tip">Gross sales minus discounts and returns.</span>
  </dds-tooltip>
  to see the definition.
</p>
```

#### Placement

Set `placement` to `top`, `bottom`, `start` or `end` to choose the side of the trigger. `start` and `end` follow the writing direction, so they swap in right-to-left text. The tooltip flips to the opposite side when there is no room.

```html
<dds-tooltip placement="end">
  <dds-button slot="trigger">Options</dds-button>
  <span>Opens beside the trigger.</span>
</dds-tooltip>
```

#### Size

Set `size` to `s`, `m` or `l` to change how wide the tooltip can grow before its text wraps. Use `s` for a short label, `l` for a formula or a sentence or two, and leave `m` for most content.

```html
<dds-tooltip size="l">
  <dds-button slot="trigger">Total sales</dds-button>
  <span
    >Gross sales minus discounts and returns, plus shipping, taxes, duties and
    fees.</span
  >
</dds-tooltip>
```

#### Keyboard

The tooltip follows the [APG tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/): it appears when the trigger receives focus, and `Esc` dismisses it without moving focus. It does not take focus itself, so keep the content to text and never put a link or button inside it. Touch does not open a tooltip, so never use one as the only way to reach essential information.



## Properties

| Property    | Attribute   | Description                                                            | Type                                    | Default |
| ----------- | ----------- | ---------------------------------------------------------------------- | --------------------------------------- | ------- |
| `placement` | `placement` | The side of the trigger the tooltip prefers. It flips to stay in view. | `"bottom" \| "end" \| "start" \| "top"` | `"top"` |
| `size`      | `size`      | The maximum width of the tooltip.                                      | `"l" \| "m" \| "s"`                     | `"m"`   |


## Slots

| Slot        | Description                                                     |
| ----------- | --------------------------------------------------------------- |
|             | The content of the tooltip.                                     |
| `"trigger"` | The element the tooltip is anchored to, such as a `dds-button`. |


## Shadow Parts

| Part     | Description         |
| -------- | ------------------- |
| `"root"` | The floating panel. |


----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*