# Tooltip
Package: @nannier/canvas
Version: 4.0.0
Status: source-snapshot (not proof of an npm release)
Source SHA-256: d245658f4bbe4b0d228e837d45b679ef7d0b430b11e0391463a008af7a4548de
Source: `src/atoms/tooltip/tooltip.md`
Human reference: https://canvas.nannier.com/components/tooltip
## Public imports
```tsx
import { Tooltip } from "@nannier/canvas";
```
The following examples are source excerpts. Supply application data and handlers; snippets using `tokens` read `const { tokens } = useTheme()` inside a component. Import React hooks from React. Intentional “Don't” examples illustrate unsupported patterns.
Small floating helper text on hover or focus.
The bubble floats over the page: it is drawn in the overlay layer of the nearest
`OverlayProvider`, placed against its trigger, and changes no layout, so a tip on a
table row's action never grows the cell. It centers on the trigger at the side you
pick, flips to the opposite side when the visible area has no room there, and slides
to stay inside it. Moving the pointer from the trigger onto the bubble keeps it up.
With no `OverlayProvider` mounted it still floats, on an absolute anchor beside the
trigger, but an ancestor that clips its content can then cut it off.
The bubble inverts against the page (dark in the light scheme, light in the dark one)
and sets its text in Dark Factory's label type;
iOS, which has no tooltip, shows the
same bubble, and Android keeps the Material 3 plain tooltip.
The trigger is a boolean axis of its own, resolved first match wins:
- `children`, an element you already have (an icon `Button`, a `Chip`, any
control that owns its own press and accessible name). The child renders as-is
and the tip hangs off it through a wrapper that only LISTENS: no accessibility
role, no tab stop, and no press of its own, so the child stays the single
interactive, labelled element, keeps its `onPress`, and the tip never toggles
on tap. Hover and focus on the child both raise it.
- `iconTrigger`, a ghost icon button carrying a settings glyph.
- `textTrigger`, the `trigger` string as a pressable inline word.
- Otherwise the default: the `trigger` string as an outline Button.
Hover and focus are pointer-and-keyboard affordances. Touch pointers are
skipped,
and iOS and Android never fire hover at all.
On touch the built-in
triggers toggle the tip on tap (tap again to close it; a tip is never modal, so a
tap elsewhere goes to the page). A long press is not taken: it belongs to the
platform and to the control. An element trigger has no tap toggle either, because
that press belongs to the child, so on native and on touch the controlled `open`
prop is the way to show its tip: drive it from whatever the platform does offer (a
long press the child handles, a selected row, an inline help toggle). Keyboard
focus, including a hardware keyboard on a tablet, raises the tip on every platform.
Escape hides an open tip and leaves focus where it is (WCAG 1.4.13: hover and focus
content is dismissable without moving the pointer or focus). It goes through the kit's
one Escape owner, so a tip inside a Dialog or Popover closes first and the next Escape
reaches its host; a closed tip takes no Escape at all. A controlled tip reports the
close through `onOpenChange(false)`.
On iOS the same close answers the accessibility
escape (the VoiceOver two-finger scrub, and Escape on a hardware keyboard under Full
Keyboard Access).
Android delivers no Escape key to a view, and its back gesture is
never taken for a tip, so there the tip closes with focus or the controlled `open`.
## Usage
The examples pinned open leave room on the bubble's side, as a page would: the
bubble floats and takes no room of its own.
```tsx
```
## Variants
### Right
```tsx
```
### Bottom
```tsx
```
### Left
```tsx
```
### Icon
```tsx
```
### Text
```tsx
```
### Element trigger
```tsx
} />
```
### On hover
```tsx
```
## Do & Don't
### Short labels
**Do** — Keep tooltips short and supplementary; put essential steps in visible copy.
```tsx
```
**Don't** — Long, essential instructions hidden in a tooltip are missed on touch and by screen readers.
```tsx
```
### Placement
**Do** — Pick the side with the most room; the tip flips and slides to stay on screen when it has none.
```tsx
```
**Don't** — Don't place a tip where it covers the control a user needs next; it floats over the page, so it masks whatever sits on that side.
```tsx
```
## Supported props
### TooltipProps
| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| children | ReactNode | no | | An arbitrary element for the tip to hang off: an existing Button, Chip, or any other control that already owns its own press and accessible name. The highest-precedence trigger: children win over `iconTrigger`, `textTrigger`, and the default Button. The child renders as-is and stays the single interactive, labelled element; the root view Tooltip wraps it in takes no accessibility role and no tab stop, listens only for hover and focus, and never claims the press, so a Button child keeps its `onPress` and the tip does not toggle on tap. |
| label | string \| undefined | no | | The tip text shown in the bubble. |
| trigger | string \| undefined | no | | The element the tip describes. By default rendered as a text `