# Tooltip

> One line that appears on hover or keyboard focus and gives something without a visible label its name, its consequence or its shortcut.

Source: https://raft-design.botiverse.build/components/tooltip. Generated from the current release; where it differs from what you remember, this page is right.

A tooltip is one line that appears on hover or keyboard focus and gives something without a visible label its name, its consequence or its keyboard shortcut. Icon buttons, truncated names, runtime chips and the items of the desktop rail use it.

## When to use

| Situation                                                                     | Use                                                                                    |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| An icon button, a truncated name, a runtime chip ("Runs on Martin's MacBook") | Tooltip                                                                                |
| An item of the desktop rail                                                   | Tooltip on the right, with the destination's name ([AppRail](https://raft-design.botiverse.build/components/app-rail.md)) |
| A label that is already visible on the control                                | Nothing: don't repeat it in a tooltip                                                  |
| Content with a link or a button                                               | [Popover](https://raft-design.botiverse.build/components/popover.md)                                                       |
| A person or an agent                                                          | [PreviewCard](https://raft-design.botiverse.build/components/preview-card.md)                                         |

## Anatomy

- `TooltipProvider`: sets the open delay for the tooltips inside it. In raft-ui they open without delay.
- `Tooltip`: the root. Required.
- `TooltipTrigger`: the element the tooltip describes. Required.
- `TooltipContent`: the tooltip, with a small arrow toward the trigger. A leading icon and a `Kbd` for the shortcut can sit inside it. Required.
- `TooltipPortal`: a lower-level part.

The tooltip is `layer-hud` with `foreground-on-hud` text, like a toast ([Color](https://raft-design.botiverse.build/foundations/color.md#surfaces)).

## Behavior

- It opens above its trigger, centered on it, and flips below when there is no room above.
- `side="right"` puts it beside the trigger, as on the rail; `side="bottom"` puts it under the trigger.
- It wraps at 20rem, or at the space left in the window.
- It closes when the pointer leaves, when focus leaves and on Esc.

## Content

- Write one name or one short sentence, in sentence case: Search, Runs on Martin's MacBook.
- Use the same word in the tooltip as in the trigger's `aria-label`.
- Put the shortcut in a `Kbd` after the text: Search ⌘K.

## Accessibility

- Tooltip wraps the Base UI Tooltip. It provides the `tooltip` role and opens on hover and on keyboard focus.
- A tooltip adds to a name; it doesn't replace it. Give every icon-only button its own `aria-label`.
- Touch screens have no hover. Show the tooltip on press and hold, or write the explanation in the interface instead.

## Rules

- Never put a link, a button or anything people must act on in a tooltip: the pointer can't reach it.

## API

### Tooltip

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<TooltipRootActions \| null>` |  | A ref to imperative actions. - `unmount`: Unmounts the tooltip popup. - `close`: Closes the tooltip imperatively when called. |
| `children` | `ReactNode \| PayloadChildRenderFunction<unknown>` |  | The content of the tooltip. This can be a regular React node or a render function that receives the `payload` of the active trigger. |
| `defaultOpen` | `boolean` | `false` | Whether the tooltip is initially open. |
| `defaultTriggerId` | `string` |  | ID of the trigger that the tooltip is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open tooltip. |
| `disabled` | `boolean` | `false` | Whether the tooltip is disabled. |
| `disableHoverablePopup` | `boolean` | `false` | Whether the tooltip contents can be hovered without closing the tooltip. |
| `handle` | `BaseTooltip.Handle<unknown>` |  | A handle to associate the tooltip with a trigger. If specified, allows external triggers to control the tooltip's open state. Can be created with the Tooltip.createHandle() method. |
| `onOpenChange` | `(open: boolean, eventDetails: BaseTooltip.Root.ChangeEventDetails) => void` |  | Event handler called when the tooltip is opened or closed. |
| `onOpenChangeComplete` | `(open: boolean) => void` |  | Event handler called after any animations complete when the tooltip is opened or closed. |
| `open` | `boolean` |  | Whether the tooltip is currently open. |
| `trackCursorAxis` | `"none" \| "both" \| "x" \| "y"` | `'none'` | Determines which axis the tooltip should track the cursor on. |
| `triggerId` | `string` |  | ID of the trigger that the tooltip is associated with. This is useful in conjunction with the `open` prop to create a controlled tooltip. There's no need to specify this prop when the tooltip is uncontrolled (that is, when the `open` prop is not set). |

### TooltipContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null>` |  |  |
| `portalProps` | `TooltipPortalProps` |  |  |
| `align` | `Align` | `"center"` | How to align the popup relative to the specified side. |
| `alignOffset` | `number \| OffsetFunction` | `0` | Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. |
| `anchor` | `Element \| VirtualElement \| RefObject<Element \| null> \| (() => Element \| VirtualElement \| null)` |  | An element to position the popup against. By default, the popup will be positioned against the trigger. |
| `arrowPadding` | `number` | `5` | Minimum distance to maintain between the arrow and the edges of the popup. |
| `collisionAvoidance` | `CollisionAvoidance` | `CONTENT_COLLISION_AVOIDANCE` | Determines how to handle collisions when positioning the popup. |
| `collisionBoundary` | `Boundary` | `'clipping-ancestors'` | An element or a rectangle that delimits the area that the popup is confined to. |
| `collisionPadding` | `Padding` | `5` | Additional space to maintain from the edge of the collision boundary. |
| `disableAnchorTracking` | `boolean` | `false` | Whether to disable the popup from tracking any layout shift of its positioning anchor. |
| `positionMethod` | `"fixed" \| "absolute"` | `"fixed"` | Determines which CSS `position` property to use. |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |
| `side` | `Side` | `"top"` | Which side of the anchor element to align the popup against. May automatically change to avoid collisions. |
| `sideOffset` | `number \| OffsetFunction` | `0` | Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. |
| `sticky` | `boolean` | `false` | Whether to maintain the popup in the viewport after the anchor element was scrolled out of view. |

Also takes the attributes of its element.

### TooltipPortal

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null>` |  | A parent element to render the portal element into. |
| `keepMounted` | `boolean` | `false` | Whether to keep the portal mounted in the DOM while the popup is hidden. |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### TooltipProvider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  |  |
| `closeDelay` | `number` |  | How long to wait before closing a tooltip. Specified in milliseconds. |
| `delay` | `number` | `0` | How long to wait before opening the tooltip on hover. Specified in milliseconds. |
| `timeout` | `number` | `400` | Another tooltip will open instantly if the previous tooltip is closed within this timeout. Specified in milliseconds. |

### TooltipTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | `0` | How long to wait before closing the tooltip. Specified in milliseconds. |
| `closeOnClick` | `boolean` | `true` | Whether the tooltip should close when this trigger is clicked. |
| `delay` | `number` | `600` | How long to wait before opening the tooltip on hover. Specified in milliseconds. |
| `disabled` | `boolean` | `false` | If `true`, the tooltip will not open when interacting with this trigger. Note that this doesn't apply the `disabled` attribute to the trigger element. If you want to disable the trigger element itself, you can pass the `disabled` prop to the trigger element via the `render` prop. |
| `handle` | `BaseTooltip.Handle<unknown>` |  | A handle to associate the trigger with a tooltip. |
| `payload` | `{}` |  | A payload to pass to the tooltip when it is opened. |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

## Changes

- 0.10.0 (Changed): `Tooltip`, `ComboboxSelect` options, `Steps` and `Timeline` use the type scale instead of fixed sizes, so they follow the desktop values.