---
title: "Tooltip"
description: "Describes an element in a few words when a person points at it, focuses it with the keyboard or long-presses it, without taking focus or blocking anything."
url: "https://tanrei.chnotchy.com/components/tooltip/"
last_updated: 2026-10-23T21:17:12.000Z
---

# Tooltip

> Describes an element in a few words when a person points at it, focuses it with the keyboard or long-presses it, without taking focus or blocking anything.

## Overview

### Usage

The anchor is your own element: an icon button, a truncated label, a chart mark. The tooltip adds a description to it and changes nothing else about it. It wraps the anchor on the web, Compose, Flutter and React Native, and is a modifier on the anchor on SwiftUI.

The tooltip opens and closes itself, on hover, keyboard focus and long-press, and reports that through `toggle`. You set `open` only to show it on your own, such as a first-run hint. Setting it emits nothing, and the tooltip keeps opening and closing itself afterwards.

`describes` (true by default) makes the text the anchor’s accessible description. Set it to false when the text repeats the anchor’s own name, as it does for an icon button whose tooltip shows its label, so that screen readers do not read the words twice.

The Web and React samples show the current spec. SwiftUI, Compose, Flutter and React Native are lagging: they still ship the previous revision of the tooltip, which has four centred placements and no per-tooltip delays, offsets, arrow, second look or shortcut, and fades without growing. Their samples show that revision until they catch up.

**Web**

```html
<!-- The tooltip wraps its anchor. no-describe is describes set to false: the text repeats the label. -->
<tanrei-tooltip text="Move to trash" no-describe>
  <tanrei-button variant="text" label="Move to trash"><span slot="icon">delete</span></tanrei-button>
</tanrei-tooltip>

<!-- A dense toolbar that wants its names sooner. Delays are in milliseconds. -->
<tanrei-tooltip text="Bold" show-delay="150" no-describe>
  <tanrei-button variant="text" label="Bold"><span slot="icon">format_bold</span></tanrei-button>
</tanrei-tooltip>

<!-- The command's keys after its name. The anchor carries them for assistive technology. -->
<tanrei-tooltip text="Bold" shortcut="mod+b" no-describe>
  <tanrei-button variant="text" label="Bold"><span slot="icon">format_bold</span></tanrei-button>
</tanrei-tooltip>

<!-- Below the control, lined up with its start edge, with an arrow, on a surface instead of inverse. -->
<tanrei-tooltip text="Filter by date or by owner" placement="bottom-start" arrow inverse="false">
  <tanrei-button variant="text" label="Filter"><span slot="icon">filter_list</span></tanrei-button>
</tanrei-tooltip>

<tanrei-tooltip id="storage" variant="rich" headline="Storage" placement="bottom"
                text="Files in the trash still count toward your storage until they are deleted.">
  <tanrei-button variant="text" label="About storage"><span slot="icon">info</span></tanrei-button>
</tanrei-tooltip>

<script type="module">
  import '@tanrei/web/components/tooltip';
  const storage = document.querySelector('#storage');
  // A first-run hint. Setting open emits nothing.
  storage.open = true;
  // toggle reports what the tooltip did by itself: hover, focus, long-press, Escape, the timeout, another tooltip.
  storage.addEventListener('toggle', (e) => console.log(e.detail.open));
</script>
```

**React**

```tsx
import { Button, Tooltip } from '@tanrei/react';

<Tooltip text="Move to trash" describes={false}>
  <Button variant="text" label="Move to trash" onClick={trash}><span slot="icon">delete</span></Button>
</Tooltip>
{/* The command's keys after its name: one chord per string. */}
<Tooltip text="Bold" shortcut={['mod+b']} describes={false}>
  <Button variant="text" label="Bold" onClick={bold}><span slot="icon">format_bold</span></Button>
</Tooltip>
{/* Below the control, lined up with its start edge, with an arrow, on a surface instead of inverse. */}
<Tooltip text="Filter by date or by owner" placement="bottom-start" arrow inverse={false}>
  <Button variant="text" label="Filter" onClick={filter}><span slot="icon">filter_list</span></Button>
</Tooltip>
<Tooltip
  variant="rich"
  headline="Storage"
  text="Files in the trash still count toward your storage until they are deleted."
  placement="bottom"
  touchTimeout={4000} // a few sentences need longer to read after a long-press
  onToggle={(e) => log(e.detail.open)}
>
  <Button variant="text" label="About storage"><span slot="icon">info</span></Button>
</Tooltip>
```

**SwiftUI**

```swift
import Tanrei

// A modifier on the anchor. .tanreiTheme(_:) above it hosts the layer the tooltip is drawn in.
// The description becomes the anchor's accessibilityHint.
TanreiIconButton("Move to trash", action: trash) { Image(systemName: "trash") }
    .tanreiTooltip("Move to trash", describes: false)

// isPresented is open; the tooltip writes it when it opens or closes by itself.
TanreiIconButton("About storage", action: {}) { Image(systemName: "info.circle") }
    .tanreiTooltip("Files in the trash still count toward your storage until they are deleted.",
                   title: "Storage", variant: .rich, placement: .bottom, isPresented: $showHint)
```

**Compose**

```kotlin
import io.github.chnotchy.tanrei.components.TanreiIconButton
import io.github.chnotchy.tanrei.components.TanreiTooltip
import io.github.chnotchy.tanrei.components.TanreiTooltipPlacement
import io.github.chnotchy.tanrei.components.TanreiTooltipVariant
import io.github.chnotchy.tanrei.components.rememberTanreiTooltipState
import io.github.chnotchy.tanrei.primitives.TanreiText

// As Material's TooltipBox: the tooltip wraps its anchor.
TanreiTooltip(text = "Move to trash", describes = false) {
    TanreiIconButton(onClick = ::trash, contentDescription = "Move to trash") { TanreiText("delete") }
}

// The state is open. onToggle hears what the tooltip does by itself; show() and dismiss() emit nothing.
val hint = rememberTanreiTooltipState(onToggle = { open -> log(open) })
TanreiTooltip(
    text = "Files in the trash still count toward your storage until they are deleted.",
    variant = TanreiTooltipVariant.Rich,
    title = "Storage",
    placement = TanreiTooltipPlacement.Bottom,
    state = hint,
) {
    TanreiIconButton(onClick = {}, contentDescription = "About storage") { TanreiText("info") }
}
LaunchedEffect(Unit) { hint.show() } // a first-run hint
```

**Flutter**

```dart
import 'package:tanrei/tanrei.dart';

// show() and hide() set open, and notify nobody. Listeners hear what the tooltip does by itself.
final TanreiTooltipController hint = TanreiTooltipController();
hint.addListener(() => log(hint.isOpen));

// As Flutter's Tooltip: message is the text, and excludeFromSemantics is describes, inverted.
TanreiTooltip(
  message: 'Move to trash',
  excludeFromSemantics: true, // the text repeats the button's own name
  child: TanreiIconButton(onPressed: trash, icon: const Icon(AppSymbols.delete), semanticLabel: 'Move to trash'),
);
TanreiTooltip(
  variant: TanreiTooltipVariant.rich,
  title: 'Storage',
  message: 'Files in the trash still count toward your storage until they are deleted.',
  placement: TanreiTooltipPlacement.bottom,
  controller: hint, // hint.show() for a first-run hint
  child: TanreiIconButton(onPressed: info, icon: const Icon(AppSymbols.info), semanticLabel: 'About storage'),
);
```

**React Native**

```tsx
import { IconButton, Tooltip } from '@tanrei/react-native';

// The anchor is ONE child that takes a Pressable's props. The tooltip adds its handlers, calling the anchor's own first.
<Tooltip text="Move to trash" describes={false}>
  <IconButton accessibilityLabel="Move to trash" onPress={trash}>delete</IconButton>
</Tooltip>

// open shows it from your code and emits nothing; onOpenChange hears what it does by itself.
<Tooltip
  variant="rich"
  headline="Storage"
  text="Files in the trash still count toward your storage until they are deleted."
  placement="bottom"
  open={showHint}
  onOpenChange={setShowHint}
>
  <IconButton accessibilityLabel="About storage">info</IconButton>
</Tooltip>
```

## Specs

- Category: Communication
- Level: base
- Listing: default
- Page: https://tanrei.chnotchy.com/components/tooltip/
- Spec: https://github.com/chnotchy/tanrei/blob/main/specs/tooltip.spec.json

### Availability

| Design system | Has it | Notes |
| --- | --- | --- |
| Tanrei (`tanrei`) | Yes | — |
| Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — |
| M3 Expressive-like (Material 3 Expressive-inspired) (`m3-expressive-like`) | Yes | — |
| M3-like (Material 3-inspired) (`m3-like`) | Yes | — |

### Platforms

- Web: the element `<tanrei-tooltip>`, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/tooltip`).
- React: `Tooltip` from `@tanrei/react`.

| Platform | Name | Status |
| --- | --- | --- |
| Web | `tanrei-tooltip` | lagging |
| SwiftUI | `tanreiTooltip` | lagging |
| Jetpack Compose | `TanreiTooltip` | lagging |
| Flutter | `TanreiTooltip` | lagging |
| React Native | `Tooltip` | lagging |

Names a platform gives in its own idiom:

| Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
| --- | --- | --- | --- | --- | --- |
| `text` (prop) | `text` | `text` | `text` | `message` | `text` |
| `title` (prop) | `headline` | `title` | `title` | `title` | `title` |
| `describes` (prop) | `describes` | `describes` | `describes` | `excludeFromSemantics` | `describes` |
| `open` (prop) | `open` | `isPresented` | `state` | `controller` | `open` |
| `showDelay` (prop) | `showDelay` | `showDelay` | `showDelayMillis` | `waitDuration` | `showDelay` |
| `hideDelay` (prop) | `hideDelay` | `hideDelay` | `hideDelayMillis` | `exitDuration` | `hideDelay` |
| `touchTimeout` (prop) | `touchTimeout` | `touchTimeout` | `touchTimeoutMillis` | `showDuration` | `touchTimeout` |
| `toggle` (event) | `toggle` | `isPresented` | `state` | `controller` | `onOpenChange` |

Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal.

### Anatomy

- `anchor`: The element the tooltip describes: the product's own (an icon-only Button, a truncated label, a chart mark). The tooltip adds a description to it and changes nothing else about it.
- `container`: The surface that holds the text, placed on one side of the anchor and aligned along it.
- `arrow` (optional): A triangle on the container's edge that faces the anchor, pointing at it; one shape with the container.
- `title` (optional): A short heading above the supporting text. Rich tooltips only.
- `supporting-text`: The description. A plain tooltip holds nothing else.
- `shortcut` (optional): The keys that perform the anchor's command, after the text. Plain tooltips only.

### Props

| Prop | Type | Default | Web attribute | Description |
| --- | --- | --- | --- | --- |
| `variant` | `enum`: `plain`, `rich` | `"plain"` | `variant` | Plain is one short phrase, by default on the inverse surface, for naming what an icon does. Rich is an optional title and a few sentences, by default on a raised surface, for explaining a term or a setting. A structural choice drawn by code, not a token axis: a design system cannot add a form by values. |
| `text` | `string` | `""` | `text` | The description. Required. |
| `title` | `string` | `""` | — | A heading for a rich tooltip. Ignored by a plain one. |
| `shortcut` | `strings` | `` | `shortcut` | The keyboard shortcut of the anchor's command, in the keyboard shortcut component's key names: one chord per string, pressed in order (["mod+b"]). A plain tooltip draws it after the text for the keyboard the person uses and exposes it as the anchor's keyboard shortcut (TIP-27); a rich one ignores it. It does not make the keys work; the product binds them. |
| `placement` | `enum`: `top`, `top-start`, `top-end`, `bottom`, `bottom-start`, `bottom-end`, `start`, `start-top`, `start-bottom`, `end`, `end-top`, `end-bottom`, `auto` | `"top"` | `placement` | Where the tooltip prefers to stand: a side of the anchor, and how it lines up along that side (TIP-22). top and bottom centre it above or below the anchor; with -start or -end its start or end edge meets the anchor's. start and end centre it beside the anchor; with -top or -bottom its top or bottom edge meets the anchor's. auto takes the first side with room (TIP-23). Start and end follow the layout direction. The tooltip flips to the opposite side when the preferred one has no room, keeping the alignment (TIP-9). |
| `offset` | `number` | — | `offset` | The distance between the anchor's edge and the tooltip, in the platform's layout units; 0 lets them touch. Null takes comp.tooltip.offset, the system's answer for every tooltip. Set it only where one anchor's box is not what the eye takes for its edge (a control with a large invisible hit area, a mark of a chart). |
| `crossOffset` | `number` | `0` | `cross-offset` | How far the tooltip moves along the side it stands on, in the platform's layout units, from where placement puts it: positive towards the end for a tooltip above or below, towards the bottom for one beside. For lining an aligned tooltip up with what is drawn inside the anchor rather than with the anchor's box. It never moves the tooltip off the anchor's side (TIP-24). |
| `arrow` | `boolean` | — | `arrow` | Whether the tooltip draws an arrow that points at the anchor. Null, the default, takes comp.tooltip.arrow.visible, the system's choice, which is off in the default system (TIP-25). |
| `inverse` | `boolean` | — | `inverse` | Whether this tooltip is drawn inverse: in the opposite scheme's colors, so that it stands apart from whatever it lands on. False draws it on a surface of the scheme. Null, the default, takes its form's choice: comp.tooltip.plain.container.inverse (on in the default system) or comp.tooltip.rich.container.inverse (off). It changes colors and elevation only (TIP-26). |
| `describes` | `boolean` | `true` | `no-describe` (turns it off) | Whether assistive technology reads the text as the anchor's description. Set it to false when the text repeats the anchor's own accessible name (an icon-only Button whose tooltip shows its label), so that it is not read twice. |
| `open` | `boolean` | `false` | `open` | Whether the tooltip is showing. The tooltip opens and closes itself on hover, focus and long-press and reports it (toggle). A product sets it to show a tooltip on its own (a first-run hint); a snapshot harness sets it to draw a fixture. |
| `showDelay` | `number` | — | `show-delay` | How long, in milliseconds, a fine pointer rests on the anchor before this tooltip opens; 0 opens it at once. Null takes comp.tooltip.motion.show-delay, the system's answer for every tooltip. Set it only where one tooltip needs another pace than the rest (a dense toolbar that wants its names sooner, a chart whose marks the pointer sweeps across and should not flash). It applies to hover alone: keyboard focus still opens at once. |
| `hideDelay` | `number` | — | `hide-delay` | How long, in milliseconds, this tooltip waits after the pointer has left the anchor, the gap and the tooltip before it closes; 0 closes it at once. Null takes comp.tooltip.motion.hide-delay. The tooltip stays hoverable at any value, 0 included, because the gap between the anchor and the tooltip counts as hover (TIP-1). |
| `touchTimeout` | `number` | — | `touch-timeout` | How long, in milliseconds, a tooltip opened by a long-press stays after the finger lifts; 0 closes it as the finger lifts, so it shows for as long as the press lasts. Null takes comp.tooltip.timeout.touch. Set it only where one tooltip needs more or less reading time on touch than the rest (a rich tooltip of a few sentences, a one-word name). |

### Events

| Event | Description |
| --- | --- |
| `toggle` | The tooltip opened or closed by itself (hover, focus, long-press, Escape, the touch timeout, another tooltip opening); carries the new open value. |

### Slots

| Slot | Description |
| --- | --- |
| `default` | The anchor. |

### States

`enabled`

### Accessibility

- Role: `tooltip`
- Labeling: The tooltip names nothing. The anchor keeps its own accessible name and role; while describes is true the text (after the title, for a rich tooltip) is the anchor's description, available whether or not the tooltip is showing. An icon-only Button's label is its name (BTN-16) and is never replaced by a tooltip: a tooltip that shows the same words sets describes to false. A shortcut is the anchor's keyboard shortcut where the platform has that property, and the end of its description otherwise (TIP-27); the drawn keys and the arrow are hidden.
- Minimum target size: yes

| Keys | Action |
| --- | --- |
| Tab | Moving focus to the anchor opens its tooltip at once; moving focus away closes it. The tooltip itself is never a tab stop. |
| Escape | Closes an open tooltip without moving focus, and goes no further (an enclosing dialog stays open). |

- The tooltip takes no input, so it has no target of its own: minimumTarget applies to the anchor, which keeps its own hit area.
- WCAG 1.4.13 (content on hover or focus): the tooltip can be dismissed without moving the pointer or focus (Escape, TIP-4), can be hovered (TIP-1: the gap between the anchor and the tooltip counts as hover — at any offset, with or without an arrow — so this holds at any hideDelay, 0 included), and stays until hover or focus ends or it is dismissed (TIP-5). Placement, the arrow and the motion change none of the three: a tooltip that flips, shifts or follows its anchor is the same open tooltip, and the gap is measured to wherever it stands.
- A tooltip is invisible to touch users until they long-press, and to screen-reader users it is only a description. Nothing a person needs to finish a task may live only in a tooltip. A note that needs a link or a button is not a tooltip; that form belongs to a separate non-modal popover component.
- Do not put a tooltip on a disabled anchor to explain why it is disabled: a disabled control cannot be focused, and on the web it may receive no pointer events. Put the reason in visible text.
- Web: the description reaches the anchor's focusable element as aria-description, because aria-describedby cannot point across shadow roots. The anchor is the first focusable element slotted into the tooltip; a Tanrei component forwards aria-description from its host to the native element in its shadow root. The drawn tooltip has role tooltip and aria-hidden while describes carries the text.
- The motion is short, small and never the only sign of anything; where motion is reduced nothing grows or travels (TIP-15). A tooltip that is leaving is already closed for input (TIP-29), so nothing invisible is ever in the pointer's way.
- The inverse look and the surface look are two looks of one thing, not two meanings: neither says that a tooltip matters more. Choose by what the tooltip lands on.
- A shortcut in a tooltip is a reminder for people who see it. It must also work for those who do not: the product binds the keys, and the anchor carries the shortcut for assistive technology (TIP-27).

### Behaviour

Requirements in EARS form, each with its stable id.

- **TIP-1** WHEN a fine pointer enters the anchor and stays on it for the show delay (TIP-17) THE tooltip SHALL open; WHEN the pointer leaves the anchor THE tooltip SHALL stay open while the pointer crosses the gap to the tooltip or moves onto the tooltip itself, and SHALL close once the pointer has been off the anchor, the gap and the tooltip for the hide delay (TIP-17). The gap is the strip between the anchor's edge and the container — the offset deep (TIP-24), and comp.tooltip.arrow.height deeper while an arrow is drawn (TIP-25) — as wide as the container along that side; it counts for hover alone, is not drawn and takes no press.
- **TIP-2** WHEN the anchor receives keyboard focus THE tooltip SHALL open without delay, and WHEN the anchor loses focus THE tooltip SHALL close; focus gained by pointer or touch SHALL NOT open it.
- **TIP-3** WHEN the user long-presses the anchor by touch THE tooltip SHALL open without activating the anchor, and WHEN the finger lifts SHALL stay open for the touch timeout (TIP-17) and then close; a touch anywhere else SHALL close it sooner.
- **TIP-4** WHILE the tooltip is open, WHEN the user presses Escape THE tooltip SHALL close without moving focus and SHALL consume the key, so that it does not also close an enclosing dialog; it SHALL stay closed until the anchor is entered by the pointer or focused again.
- **TIP-5** WHILE the pointer is over the anchor or the tooltip, or the anchor has keyboard focus, THE tooltip SHALL stay open with no time limit, until Escape (TIP-4), an activation of the anchor (TIP-6) or another tooltip opening (TIP-8) closes it.
- **TIP-6** WHEN the anchor is activated (a click, a tap, Enter or Space) THE tooltip SHALL close, and SHALL NOT open again from the same hover until the pointer has left the anchor and entered it again.
- **TIP-7** WHEN the tooltip opens or closes by itself (TIP-1 to TIP-6, TIP-8) THE tooltip SHALL emit toggle with the new value; WHEN the product sets open THE tooltip SHALL show or hide accordingly without emitting toggle, and SHALL then keep following TIP-1 to TIP-6.
- **TIP-8** WHEN a tooltip opens while another tooltip is open THE other tooltip SHALL close at once, and the new one SHALL open without waiting for its show delay (TIP-17), because the person is already reading tooltips; at most one tooltip SHALL be open in a window.
- **TIP-9** THE tooltip SHALL place its container on the side of the anchor and with the alignment that placement names (TIP-22, TIP-23), the offset away from the anchor's edge and moved along the side by crossOffset (TIP-24), and SHALL keep it at least comp.tooltip.window-margin inside the window's safe area by these steps, in this order: WHEN the preferred side has no room for the container and the opposite side has, it SHALL flip to the opposite side, keeping the alignment; WHEN neither has room it SHALL use the one of the two with more room; it SHALL then shift along the side as far as the margin asks and no farther; and WHERE the container is still larger than the room on its side (a window smaller than the tooltip) it SHALL move the container back into the margin over the anchor, its top and start edges first, rather than leave the window. It SHALL follow the anchor when the anchor moves (scrolling, resizing, layout), taking these steps again from the side it is on, which it SHALL keep for as long as that side has room, so that a page that scrolls does not throw the tooltip from side to side; and it SHALL close WHEN the anchor is removed, hidden, scrolled out of the window, or scrolled out of sight inside a scrolling ancestor so that no part of it can be seen.
- **TIP-10** WHILE variant is plain THE tooltip SHALL draw text in comp.tooltip.plain.supporting-text.typescale and comp.tooltip.plain.supporting-text.color on a container of comp.tooltip.plain.container.color with comp.tooltip.plain.container.shape corners and comp.tooltip.plain.container.elevation — or, WHILE it is drawn on a surface, in the colors and the elevation TIP-26 names in their place — padded by comp.tooltip.plain.container.padding-inline and comp.tooltip.plain.container.padding-block, at least comp.tooltip.plain.container.min-height tall and at most comp.tooltip.plain.container.max-width wide, wrapping longer text onto further lines; it SHALL draw its shortcut as TIP-27 says and SHALL ignore title.
- **TIP-11** WHILE variant is rich THE tooltip SHALL draw title in comp.tooltip.rich.title.typescale and comp.tooltip.rich.title.color above text in comp.tooltip.rich.supporting-text.typescale and comp.tooltip.rich.supporting-text.color, comp.tooltip.rich.container.gap apart, on a container of comp.tooltip.rich.container.color with comp.tooltip.rich.container.shape corners and comp.tooltip.rich.container.elevation — or, WHILE it is drawn inverse, in the colors and the elevation TIP-26 names in their place — padded by comp.tooltip.rich.container.padding-inline and comp.tooltip.rich.container.padding-block and at most comp.tooltip.rich.container.max-width wide; WHILE title is empty it SHALL draw the supporting text alone. THE tooltip SHALL set the title's letter-spacing by the script of its text, as every title is set (PRS-20): no negative letter-spacing WHERE its language is Chinese, Japanese or Korean, and none WHERE its script joins its letters or stacks marks on them.
- **TIP-12** THE tooltip SHALL ease its container corners by sys.shape.corner-smoothing (0 is a quarter circle, 0.6 the iOS continuous corner; a platform with only the OS curve draws it for any amount above 0), SHALL grow with enlarged text without clipping it, and SHALL start-align its text by the layout direction.
- **TIP-13** THE tooltip SHALL NOT take focus, SHALL hold nothing focusable or pressable, SHALL NOT make anything inert or dimmed, and SHALL be drawn above every other layer of its window, including an open dialog and its scrim; a press on the tooltip SHALL close it and SHALL NOT reach what lies under it.
- **TIP-14** WHILE describes is true THE tooltip SHALL expose text — preceded by title for a rich tooltip — as the anchor's accessible description, whether or not the tooltip is open, and SHALL keep the drawn tooltip from being read a second time; WHILE describes is false it SHALL add nothing to the anchor's semantics. In both cases it SHALL NOT change the anchor's accessible name or role.
- **TIP-15** WHEN the tooltip opens THE tooltip SHALL appear as every surface appears: from sys.motion.appear.opacity, sys.motion.appear.scale, sys.motion.appear.distance toward its anchor and sys.motion.appear.blur to whole, grown from the middle of its edge that faces the anchor — from its own centre WHERE sys.motion.appear.origin is center, and WHILE it covers its anchor (TIP-9) — over comp.tooltip.motion.enter-duration with comp.tooltip.motion.enter-easing, so that it comes out of the anchor's side whichever side it is on; WHEN it closes THE tooltip SHALL take it back the same way to where it started, over comp.tooltip.motion.exit-duration with comp.tooltip.motion.exit-easing. WHERE sys.behavior.appearance is unfold the scale SHALL apply along the axis that leaves the anchor only. The motion SHALL be drawn only: the place TIP-9 gives, the gap of TIP-1 and the room the tooltip is measured for are those of the tooltip at rest. WHERE motion is reduced THE tooltip SHALL only fade in and out, over sys.motion.role.reduced, with no scale, distance or blur, or appear and disappear at once on a platform whose reduced-motion setting removes every animation (Android's). WHEN it is mounted with open true THE tooltip SHALL appear without its motion while the document has not yet been first painted, and with it when it is mounted after that. A tooltip that takes over from another SHALL NOT move at all (TIP-28).
- **TIP-16** WHILE text is empty THE tooltip SHALL NOT open and SHALL add nothing to the anchor's semantics, and in debug builds SHALL report the empty text; WHILE variant is plain and title is set it SHALL report the ignored title in debug builds.
- **TIP-17** THE tooltip SHALL take its show delay from showDelay, its hide delay from hideDelay and its touch timeout from touchTimeout, each a number of milliseconds used as given (the motion dial does not scale it), so that 0 opens or closes at once: a show delay of 0 opens as the pointer enters, a hide delay of 0 closes as the pointer leaves the anchor, the gap and the tooltip, and a touch timeout of 0 closes as the finger lifts, after the tooltip has shown for the whole long-press. WHILE one of them is null THE tooltip SHALL use comp.tooltip.motion.show-delay, comp.tooltip.motion.hide-delay or comp.tooltip.timeout.touch in its place, and IF one is negative or not a finite number THE tooltip SHALL use that token likewise and in debug builds report the value it ignored.
- **TIP-18** THE tooltip SHALL treat its show delay, hide delay and touch timeout as waiting times, not motion: WHERE motion is reduced it SHALL keep them, on every platform, including one whose reduced-motion setting removes every animation. The show and hide delays SHALL govern hover alone (TIP-1), and the touch timeout the time after a long-press alone (TIP-3): keyboard focus (TIP-2), another tooltip being open (TIP-8) and the product setting open (TIP-7) SHALL NOT wait for any of them, and the long-press itself SHALL take the platform's own duration. WHEN showDelay, hideDelay or touchTimeout changes while that wait is running THE tooltip SHALL finish the running wait and use the new value from the next time that wait starts.
- **TIP-19** THE tooltip SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the tooltip is shown THE tooltip SHALL draw itself for the new direction at once, without a motion of its own, keeping its open state, the container placed again by the new direction (TIP-20).
- **TIP-20** WHEN the layout direction is right-to-left THE tooltip SHALL take the side start as the anchor's right side and the side end as its left, SHALL take the alignments -start and -end of a tooltip above or below as the right and the left edges, and a positive crossOffset of such a tooltip as a move towards the left, flipping and shifting from there as TIP-9 says; it SHALL leave the sides top and bottom, the alignments -top and -bottom, a crossOffset beside the anchor and the centring on the anchor as they are, SHALL keep auto's order of sides by their names (TIP-23), SHALL start-align a rich tooltip's title and text at the right (TIP-12) and SHALL draw a plain tooltip's shortcut at the left of its text (TIP-27).
- **TIP-21** THE tooltip SHALL lay out its title and its text as text of its own direction, isolated from the text around it: each takes the base direction of its first strong character, or the layout direction where it has none, so that a left-to-right word, a number with its sign or unit, a telephone number and an address keep their own order in a right-to-left layout and reorder nothing beside them; THE tooltip SHALL still place each and align its lines by the layout direction, not by the text's own.
- **TIP-22** THE tooltip SHALL read placement as a side and an alignment along that side: top and bottom SHALL put the container above or below the anchor with its centre on the anchor's, top-start and bottom-start with its start edge on the anchor's start edge, and top-end and bottom-end with its end edge on the anchor's end edge; start and end SHALL put it beside the anchor, on the side the layout direction gives that name, with its centre on the anchor's, start-top and end-top with its top edge on the anchor's top edge, and start-bottom and end-bottom with its bottom edge on the anchor's bottom edge. WHEN placement names a value the tooltip does not define THE tooltip SHALL place itself as the default value says and in debug builds report the unknown value; WHEN placement changes while the tooltip is shown THE tooltip SHALL take its new place at once, without a motion.
- **TIP-23** WHILE placement is auto THE tooltip SHALL try the sides in the order top, bottom, end, start and SHALL take the first that has room for the container within comp.tooltip.window-margin, or the one with the most room WHEN none has, with its centre on the anchor's, and SHALL then shift, hold and follow as TIP-9 says, keeping the side it took for as long as that side has room.
- **TIP-24** THE tooltip SHALL take the distance between the anchor's edge and the nearest part of itself — the container's edge, or the arrow's tip while an arrow is drawn — from offset, a number of the platform's layout units used as given, so that 0 lets the two touch, and from comp.tooltip.offset WHILE offset is null; it SHALL then move the container along its side by crossOffset, before the shift of TIP-9, and by no more than leaves comp.tooltip.arrow.width of the container beside the anchor, so that the tooltip still stands on the anchor's side and an arrow can still reach the anchor. IF offset is negative or not a finite number THE tooltip SHALL use comp.tooltip.offset in its place, IF crossOffset is not a finite number THE tooltip SHALL use 0, and in debug builds it SHALL report the value it ignored.
- **TIP-25** THE tooltip SHALL draw an arrow WHILE arrow is true, and WHILE arrow is null and comp.tooltip.arrow.visible is on, and none otherwise. WHILE it draws one THE tooltip SHALL draw a triangle comp.tooltip.arrow.width wide at its base and comp.tooltip.arrow.height tall on the container's edge that faces the anchor, as one shape with the container — the container's color and elevation, with no seam and no shadow between the two — its tip pointing at the middle of the part of the anchor's edge that the container stands beside, and SHALL keep its base at least comp.tooltip.arrow.inset, and at least the corner's radius, from each end of that edge, standing at the edge's middle where the edge is too short for both; the container SHALL stand comp.tooltip.arrow.height farther from the anchor, so that the tip keeps the offset (TIP-24). WHEN the container flips, shifts or follows the anchor (TIP-9) the arrow SHALL move with it to the edge that now faces the anchor and point at the anchor again, and WHILE the container covers the anchor (TIP-9) THE tooltip SHALL draw no arrow.
- **TIP-26** THE tooltip SHALL draw itself inverse — in the opposite scheme's colors — WHILE inverse is true, on a surface of the scheme WHILE inverse is false, and WHILE inverse is null as its form's choice says: comp.tooltip.plain.container.inverse for a plain tooltip and comp.tooltip.rich.container.inverse for a rich one. The tokens TIP-10 and TIP-27 name are a plain tooltip's inverse look: WHILE drawn on a surface a plain tooltip SHALL take comp.tooltip.plain.surface.container.color, comp.tooltip.plain.surface.container.elevation, comp.tooltip.plain.surface.supporting-text.color and comp.tooltip.plain.surface.shortcut.color in their place. The tokens TIP-11 names are a rich tooltip's surface look: WHILE drawn inverse a rich one SHALL take comp.tooltip.rich.inverse.container.color, comp.tooltip.rich.inverse.container.elevation, comp.tooltip.rich.inverse.title.color and comp.tooltip.rich.inverse.supporting-text.color in place of those TIP-11 names; its shape, padding, sizes, typescales, arrow, placement, motion and timing SHALL be the same either way, and WHEN inverse changes while the tooltip is shown THE tooltip SHALL draw the other look at once, keeping its open state.
- **TIP-27** WHILE variant is plain and shortcut is not empty THE tooltip SHALL draw the shortcut after the text, comp.tooltip.plain.container.gap from it and on the text's first line, with the keyboard shortcut component hosted as KBS-13 says: in its plain form, at size small, with convention auto, its legends and separators in comp.tooltip.plain.supporting-text.typescale and comp.tooltip.plain.shortcut.color; the shortcut SHALL stay whole on one line while the text wraps beside it, and the two with the gap SHALL fit within comp.tooltip.plain.container.max-width. THE tooltip SHALL expose the shortcut as the anchor's keyboard shortcut in the form KBS-12 gives (aria-keyshortcuts on the web) where the platform has that property and the anchor does not state one itself, and otherwise, WHILE describes is true, SHALL add the text KBS-10 gives to the end of the anchor's description; it SHALL NOT make the keys work. WHILE variant is rich THE tooltip SHALL ignore shortcut and in debug builds report it.
- **TIP-28** WHEN a tooltip opens while another tooltip of its window is open or still fading out, or within comp.tooltip.motion.warm-duration after one closed because the pointer or the keyboard focus left its anchor THE tooltip SHALL appear whole in its place at once, without the motion of TIP-15, and the other SHALL disappear at once, without its own; WHEN it is a pointer that opens it within that time THE tooltip SHALL NOT wait for its show delay either, as TIP-8 says of a tooltip that opens while another is open. A tooltip closed by Escape (TIP-4), by an activation of its anchor (TIP-6) or by a press on it (TIP-13) SHALL start no such time, so that the next tooltip waits and moves as a first one does. The time is a waiting time: WHERE motion is reduced it SHALL still apply (TIP-18).
- **TIP-29** WHEN the tooltip is told to close while it is still entering, or to open while it is still leaving THE tooltip SHALL turn round from the opacity, the size and the position it has reached, without first jumping to the start or the end of either motion, and SHALL take no longer over the rest than the whole duration of the motion it turns to. WHILE the tooltip is closed or leaving THE tooltip SHALL take no pointer input — a press reaches what lies under it, and the pointer on it is not hover (TIP-1) — and WHILE it is closed it SHALL take no room in the layout and draw nothing, so that a tooltip nobody can see never stands in the way of what is under it.

### Tokens

As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.tooltip.…` → `--tanrei-comp-tooltip-…`).

#### `tanrei.comp.tooltip`

| Token | Type | Value |
| --- | --- | --- |
| `comp.tooltip.offset` | `dimension` | `{tanrei.sys.space.space50}` |
| `comp.tooltip.window-margin` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.tooltip.arrow.visible` | `number` | `0` |
| `comp.tooltip.arrow.width` | `dimension` | `{tanrei.sys.space.space150}` |
| `comp.tooltip.arrow.height` | `dimension` | `{tanrei.sys.space.space75}` |
| `comp.tooltip.arrow.inset` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.tooltip.plain.container.inverse` | `number` | `1` |
| `comp.tooltip.plain.container.color` | `color` | `{tanrei.sys.color.inverse-surface}` |
| `comp.tooltip.plain.container.elevation` | `shadow` | `{tanrei.sys.elevation.level0}` |
| `comp.tooltip.plain.container.shape` | `dimension` | `{tanrei.sys.shape.corner.small}` |
| `comp.tooltip.plain.container.padding-inline` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.tooltip.plain.container.padding-block` | `dimension` | `{tanrei.sys.space.space50}` |
| `comp.tooltip.plain.container.min-height` | `dimension` | `24px` |
| `comp.tooltip.plain.container.max-width` | `dimension` | `200px` |
| `comp.tooltip.plain.container.gap` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.tooltip.plain.supporting-text.color` | `color` | `{tanrei.sys.color.inverse-on-surface}` |
| `comp.tooltip.plain.supporting-text.typescale` | `typography` | `{tanrei.sys.typescale.body-small}` |
| `comp.tooltip.plain.shortcut.color` | `color` | `{tanrei.sys.color.inverse-on-surface}` |
| `comp.tooltip.plain.surface.container.color` | `color` | `{tanrei.sys.color.surface-bright}` |
| `comp.tooltip.plain.surface.container.elevation` | `shadow` | `{tanrei.sys.elevation.level2}` |
| `comp.tooltip.plain.surface.supporting-text.color` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.tooltip.plain.surface.shortcut.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.tooltip.rich.container.inverse` | `number` | `0` |
| `comp.tooltip.rich.container.color` | `color` | `{tanrei.sys.color.surface-bright}` |
| `comp.tooltip.rich.container.elevation` | `shadow` | `{tanrei.sys.elevation.level2}` |
| `comp.tooltip.rich.container.shape` | `dimension` | `{tanrei.sys.shape.corner.medium}` |
| `comp.tooltip.rich.container.padding-inline` | `dimension` | `{tanrei.sys.space.space200}` |
| `comp.tooltip.rich.container.padding-block` | `dimension` | `{tanrei.sys.space.space150}` |
| `comp.tooltip.rich.container.gap` | `dimension` | `{tanrei.sys.space.space50}` |
| `comp.tooltip.rich.container.max-width` | `dimension` | `320px` |
| `comp.tooltip.rich.title.color` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.tooltip.rich.title.typescale` | `typography` | `{tanrei.sys.typescale.heading-6}` |
| `comp.tooltip.rich.supporting-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.tooltip.rich.supporting-text.typescale` | `typography` | `{tanrei.sys.typescale.body}` |
| `comp.tooltip.rich.inverse.container.color` | `color` | `{tanrei.sys.color.inverse-surface}` |
| `comp.tooltip.rich.inverse.container.elevation` | `shadow` | `{tanrei.sys.elevation.level0}` |
| `comp.tooltip.rich.inverse.title.color` | `color` | `{tanrei.sys.color.inverse-on-surface}` |
| `comp.tooltip.rich.inverse.supporting-text.color` | `color` | `{tanrei.sys.color.inverse-on-surface}` |
| `comp.tooltip.motion.show-delay` | `duration` | `{tanrei.sys.motion.duration.long2}` |
| `comp.tooltip.motion.hide-delay` | `duration` | `{tanrei.sys.motion.duration.short2}` |
| `comp.tooltip.motion.warm-duration` | `duration` | `{tanrei.sys.motion.duration.medium2}` |
| `comp.tooltip.motion.enter-duration` | `duration` | `{tanrei.sys.motion.role.appear.hint.enter}` |
| `comp.tooltip.motion.enter-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.enter}` |
| `comp.tooltip.motion.exit-duration` | `duration` | `{tanrei.sys.motion.role.appear.hint.exit}` |
| `comp.tooltip.motion.exit-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.exit}` |
| `comp.tooltip.timeout.touch` | `duration` | `1500ms` |

## Guidelines

### When to use

Use a tooltip to name an icon action for a person who does not recognise the glyph, or to explain a term, a limit or a setting on the spot. It is a description, read in passing.

A tooltip is invisible to touch users until they long-press, and a screen reader hears it only as a description. Never put anything a person needs to finish a task only in a tooltip: show it as text on the screen. A note that needs a link or a button is not a tooltip. Use a dialog, or text beside what it explains.

### Choosing a variant

| Variant | What it is | Use for |
| --- | --- | --- |
| Plain | One short phrase, by default on the inverse surface. It ignores `headline`, and can show a keyboard shortcut after its text. | Naming what an icon does: “Move to trash”, “Share”. |
| Rich | An optional title above a few sentences, by default on a raised surface. It ignores `shortcut`. | Explaining a term or a setting: “Storage” and what counts toward it. |

The variant is a structural choice, not a token axis. A design system restyles both forms, but cannot add a third by values.

### Placement

`placement` names the side of the anchor the tooltip prefers and how it lines up along that side. The default is `top`.

| Side | Centred on the anchor | First edges together | Second edges together |
| --- | --- | --- | --- |
| Above | `top` | `top-start` | `top-end` |
| Below | `bottom` | `bottom-start` | `bottom-end` |
| Before the anchor | `start` | `start-top` | `start-bottom` |
| After the anchor | `end` | `end-top` | `end-bottom` |

- **Aligned means edge on edge.** `top-start` puts the tooltip’s start edge on the anchor’s start edge, and `end-bottom` puts its bottom edge on the anchor’s bottom edge. Use an aligned placement for a wide tooltip on a small anchor near the edge of a panel, or to line a tooltip up with a row of text.
- **Start and end follow the layout direction.** In a right-to-left layout `start` is the right side and `top-start` lines up the right edges. Top and bottom do not mirror.
- **`auto`** tries top, bottom, end and start in that order and takes the first side with room, centred. Use it for an anchor whose surroundings you cannot know, such as a control in a panel that may be docked at any edge.
- **When there is no room.** The tooltip flips to the opposite side and keeps its alignment, then shifts along the side to stay inside the window’s safe area. In a window smaller than the tooltip it stays inside the window, over the anchor if it must. Once it has flipped it keeps that side for as long as the side has room, so a scrolling page does not throw it back and forth.
- **`offset` and `crossOffset`.** `offset` is the distance from the anchor’s edge, and 0 lets the two touch; left unset it is the system’s distance. `crossOffset` moves the tooltip along its side, towards the end above or below the anchor and towards the bottom beside it, and never off the anchor’s side. Both are in the platform’s layout units. Set them only where the anchor’s box is not what the eye takes for its edge, such as a control with a large invisible hit area or a mark in a chart.
- **A change while showing.** A new `placement` or offset moves the tooltip at once, without motion.

### An arrow

`arrow` draws a small triangle on the tooltip’s edge that points at the anchor. It is off in the default system. Left unset, it takes the design system’s choice; `true` and `false` decide it for one tooltip. On the web the attribute is `arrow` for true and `arrow="false"` for false.

The arrow is one shape with the tooltip, in the same color. It points at the anchor, not at the tooltip’s middle, also after the tooltip has flipped or shifted, and it keeps clear of the corners. The tooltip stands the arrow’s height farther away, so the gap you see is the same with or without one.

Use an arrow where the side alone does not say which control is meant: a hint you open yourself over a crowded toolbar, for example. Names shown on hover rarely need one.

### Two looks

Either form can be drawn inverse, in the opposite scheme’s colors, or on a raised surface of the scheme.

| `inverse` | Plain | Rich |
| --- | --- | --- |
| Not set (the default) | As the design system chooses for plain tooltips: inverse in the default system. | As the design system chooses for rich tooltips: a surface in the default system. |
| `true` | Inverse. | Inverse. |
| `false` | On a surface. | On a surface. |

On the web the attribute is `inverse` for true and `inverse="false"` for false, as the [snackbar](https://tanrei.chnotchy.com/components/snackbar/)’s is.

Only colors and elevation change. The shape, the sizes, the text styles, the arrow, the placement and the motion are the same in both looks, and neither look says that a tooltip is important. Set it for one tooltip that would otherwise have nothing to stand apart from: a dark label over a dark image viewer or on an inverse bar, or a longer note over a busy raised surface.

### A keyboard shortcut

`shortcut` shows the keys of the anchor’s command after a plain tooltip’s text, written for the keyboard the person uses. It takes the key names of the [keyboard shortcut](https://tanrei.chnotchy.com/components/keyboard-shortcut/) component, one chord per string; on the web the attribute holds the chords separated by spaces.

The tooltip only shows the keys. It does not make them work: your product binds them. The keys stay whole on one line while a long text wraps beside them. A rich tooltip ignores `shortcut` and reports it in debug builds.

### Opening, focus and closing

A tooltip is a read overlay. People take information from it and never act inside it, so it never takes focus.

| Input | Opens | Closes |
| --- | --- | --- |
| A pointer | After it rests on the anchor for the show delay. | After it has been off the anchor, the gap and the tooltip for the hide delay. The pointer can cross the gap onto the tooltip to read it. |
| Keyboard focus | At once, when the anchor gets keyboard focus. Focus from a pointer or touch does not open it. | When focus leaves the anchor. |
| A touch long-press | At once, without activating the anchor. | After the touch timeout once the finger lifts, or sooner at a touch anywhere else. |

- **No time limit while in use.** While the pointer is over the anchor, the tooltip or the gap between them, or the anchor has keyboard focus, it stays open. The gap is not drawn and takes no press: it only counts as hover.
- **Escape.** Escape closes it without moving focus, and goes no further, so an enclosing dialog stays open. It stays closed until the anchor is entered or focused again.
- **Activation.** Activating the anchor (a click, a tap, Enter or Space) closes it, and the same hover does not open it again.
- **One at a time.** When a tooltip opens, any other one in the window closes, and the new one opens without the delay, because the person is already reading tooltips.
- **Moving between tooltips.** A tooltip that takes over from another, or opens a short time after one closed because the pointer or the focus left its anchor, appears whole at once: no delay and no motion. So a pointer that sweeps along a toolbar reads one name after the next. A tooltip closed by Escape, by activating its anchor or by a press on it does not start that time.
- **Takes no focus, blocks nothing.** It holds nothing focusable or pressable, makes nothing inert and draws no scrim. A press on the tooltip closes it and does not reach what lies under it.
- **Above everything.** It is drawn above every other layer of its window, including an open dialog and its scrim, so a tooltip inside a dialog is visible.
- **Placement.** It stands where `placement` says; see [Placement](https://tanrei.chnotchy.com/components/tooltip/#placement). It follows the anchor as it moves, and closes when the anchor is removed, hidden, scrolled out of the window, or scrolled out of sight inside a scrolling area.
- **Motion.** It comes out of the anchor’s side, as every surface of the design system appears: by default it fades in while it grows a little from the middle of the edge that faces the anchor, and goes back the same way. A motion that is interrupted turns round from where it is. While it is closing, the tooltip takes no pointer, so it never stands in the way of what is under it. Where motion is reduced it only fades.
- **Announcement.** Nothing is announced when the tooltip appears. While `describes` is true, its text, after the title for a rich tooltip, is the anchor’s description whether the tooltip is open or not, and the drawn tooltip is kept from being read a second time.

### Delays for one tooltip

The design system sets the show delay, the hide delay and the touch timeout for every tooltip at once. One tooltip can set its own with `showDelay`, `hideDelay` and `touchTimeout`, in milliseconds. Left unset, each takes the system’s value.

- **When to set them.** Set a shorter show delay in a dense toolbar that wants its names sooner, and a longer one over a chart whose marks the pointer sweeps across, so that no tooltip flashes. Set a longer touch timeout on a rich tooltip of a few sentences, and a shorter one on a one-word name.
- **0 means at once.** A show delay of 0 opens the tooltip as the pointer enters the anchor, and a hide delay of 0 closes it as the pointer leaves the anchor, the gap and the tooltip. The tooltip stays hoverable even then, because the gap counts as hover. A touch timeout of 0 closes it as the finger lifts, after it has shown for the whole long-press.
- **Used as written.** A value you set is not scaled by the motion dial, and reduced motion keeps it: a delay is a wait, not an animation. A negative or non-numeric value takes the system’s value and is reported in debug builds. On the web, an empty attribute is not a number either.
- **Hover and touch only.** Keyboard focus still opens the tooltip at once, a tooltip opened while another is showing still skips its show delay, and setting `open` still shows or hides it at once. The long-press itself takes the platform’s own duration.
- **A change while waiting.** A wait that is already running finishes as it started. The new value applies the next time.

Today only the web and React take these props. When the other platforms catch up, the spec names them in each platform’s idiom: `showDelayMillis`, `hideDelayMillis` and `touchTimeoutMillis` on Compose, Flutter `Tooltip`’s `waitDuration`, `exitDuration` and `showDuration`, and the spec’s own names on SwiftUI and React Native.

Each platform uses a non-modal presentation: a `popover="manual"` element in the top layer on the web, an overlay above the window on SwiftUI (not `.popover`, which is modal at compact widths), a `Popup` that cannot take focus on Compose, an `OverlayPortal` on Flutter, and the overlay layer of `TanreiProvider` on React Native (not a `Modal`, which takes every touch).

### Do

- Keep plain tooltips to a few words, and rich tooltips to a few sentences.
- Give the same kind of anchor the same placement across a screen, such as below every icon in a toolbar.
- Leave `inverse` and `arrow` to the design system for most tooltips, and set them for the one that needs it.
- Show a command’s keys with `shortcut`, not by typing them into the text.
- Give the tooltips of one group of anchors the same delays, so that they keep one pace.
- Set `describes` to false when the tooltip shows the anchor’s own label.

### Don’t

- Don’t use a tooltip as the name of an icon button. The button’s `label` is its name.
- Don’t put a tooltip on a disabled anchor to explain why it is disabled. A disabled control cannot be focused and may receive no pointer events. Put the reason in visible text.
- Don’t put links, buttons or anything else interactive in a tooltip.
- Don’t repeat in a tooltip what the anchor already says in visible text.
- Don’t use the inverse look or an arrow to make a tooltip seem more important.

## Accessibility

### What the component handles

- While `describes` is true, the text, after the title for a rich tooltip, is the anchor’s accessible description, available whether or not the tooltip is showing. The anchor keeps its own name and role. While `describes` is false, the tooltip adds nothing to the anchor.
- The drawn tooltip is kept from being read twice. It never takes focus and holds nothing focusable.
- Keyboard focus on the anchor opens it at once, and moving focus away closes it. The tooltip itself is never a Tab stop.
- Escape closes it without moving focus, and does not also close an enclosing dialog.
- It meets WCAG 1.4.13 (content on hover or focus): it can be dismissed without moving the pointer or focus, it can be hovered at any hide delay, 0 included, because the gap between the anchor and the tooltip counts as hover, and it stays until hover or focus ends or it is dismissed.
- It grows with larger text without clipping it, and its text is aligned to the start of the layout direction.
- A shortcut is exposed as the anchor’s keyboard shortcut (`aria-keyshortcuts` on the web, on the element that takes focus), and the drawn keys are hidden from assistive technology. Where the anchor already states a shortcut of its own, the tooltip’s keys are spelled out at the end of the description instead, while `describes` is true.
- The arrow is decoration and is hidden from assistive technology. Both looks use pairs of text and container colors whose contrast the build checks in every scheme.
- Its motion is small: by default a fade and a slight growth. Where motion is reduced it fades without growing or travelling, except on Android, whose setting removes every animation. The delays, the touch timeout and the time during which the next tooltip opens at once are waits, not motion, and are kept everywhere.
- A tooltip whose text is empty never opens and adds nothing. Debug builds report it, and a plain tooltip’s ignored title.

Known platform gaps:

- SwiftUI, Compose, Flutter and React Native do not take `showDelay`, `hideDelay` or `touchTimeout` yet, and do not count the gap as hover: every tooltip there takes the system’s delays, and the pointer crosses the gap within the hide delay. They also have only the four centred placements (`top`, `bottom`, `start`, `end`), and no `offset`, `crossOffset`, `arrow`, `inverse` or `shortcut`; their tooltips fade without growing or travelling.
- Web: a touch long-press opens a tooltip only where the browser reports it as a context menu. iOS Safari does not, so there a tooltip does not open by touch.
- Web: the rich tooltip’s title is the `headline` attribute. A `title` attribute on `<tanrei-tooltip>` is the browser’s own, and the browser draws its native tooltip for it: don’t set one.
- SwiftUI has no tooltip role. The description is the anchor’s accessibility hint.
- SwiftUI on iOS: Return or Space on a focused anchor does not close the tooltip, and Escape closes it only while the anchor has focus. An anchor that takes focus from a tap, such as a text field, opens its tooltip. An anchor that is made transparent or covered is not detected as hidden.
- SwiftUI draws tooltips in a layer that `.tanreiTheme(_:)` and a Tanrei dialog provide. Content that SwiftUI presents apart, such as your own `.sheet` or `.popover`, needs `.tanreiTooltipLayer()` for its tooltips to show.
- Compose has no description property. The text becomes the anchor’s state description, read after its name and role. A Tanrei control puts it on its own node; any other anchor is described only when a merging ancestor picks it up. On a toggle anchor, such as a toggle icon button, it replaces the On or Off.
- Compose: a tooltip that you show from code on an anchor behind an open dialog is drawn under the dialog’s window.
- Compose: while focus is elsewhere in the window and the anchor was only hovered, Escape reaches the tooltip only on Android 9 (API 28) and later.
- Compose: hover from a real mouse, a touch outside, the Escape listener and TalkBack reading the anchor’s state description have been tested on Robolectric only, not yet on a device.
- Flutter: the drawn tooltip is always excluded from semantics, because Flutter’s tooltip role cannot be used yet. The description on the anchor is unaffected.
- Flutter: Escape is consumed only while focus is in the anchor, or by a Tanrei dialog. Another ancestor that handles Escape, such as a Material dialog route, still receives it while focus is elsewhere.
- React Native: the description is the anchor’s `accessibilityHint`, after the anchor’s own hint.
- React Native: a touch elsewhere does not close a long-pressed tooltip sooner. The touch timeout still closes it.
- React Native: the tooltip does not follow an anchor that scrolls, and does not close when the anchor scrolls out of view. It keeps inside the safe area only when you pass the window’s insets to `TanreiProvider`.
- React Native: hover, moving the pointer onto the tooltip, long-press and Escape have not yet been checked on a device.

### What you need to do

- Give the anchor its own accessible name. The tooltip never replaces it.
- Set `describes` to false when the text repeats that name.
- Bind the keys you show with `shortcut` yourself, and show the same keys wherever else the command appears, such as in a menu.
- Make the anchor focusable, so keyboard users can open the tooltip.
- If you shorten the touch timeout, make sure the text can still be read in the time left. A timeout of 0 shows the tooltip only while the finger is down.
- Keep everything a person needs outside the tooltip. Touch and screen-reader users may never see it.
- On React Native, put `TanreiProvider` at the root of your app, with the window’s `insets`: its overlay layer draws the tooltip inside the safe area. On SwiftUI, apply `.tanreiTheme(_:)` above the anchor, and `.tanreiTooltipLayer()` to the content of your own sheets and popovers. On Flutter, the tooltip needs an `Overlay` above it, which every `WidgetsApp` with a `Navigator` has.