# Tooltip
A small popup that describes the element it is attached to, shown on hover or focus.
## Installation
```tsx
import { Tooltip } from "@makeplane/propel/components/tooltip";
```
## Usage
```tsx
import { Button } from "@makeplane/propel/components/button";
import { Tooltip } from "@makeplane/propel/components/tooltip";
export default function BasicDemo() {
return (
);
}
```
## Examples
### Placement
The `side` prop chooses which edge the popup attaches to. It may flip automatically to stay in view.
```tsx
import { Button } from "@makeplane/propel/components/button";
import { Tooltip } from "@makeplane/propel/components/tooltip";
export default function PlacementDemo() {
return (
);
}
```
### With arrow
The default tooltip is a flat surface (no caret). Pass `showArrow` when you need a caret pointing back at the trigger.
```tsx
import { Button } from "@makeplane/propel/components/button";
import { Tooltip } from "@makeplane/propel/components/tooltip";
export default function WithArrowDemo() {
return (
);
}
```
### With shortcut
```tsx
import { Button } from "@makeplane/propel/components/button";
import { Tooltip } from "@makeplane/propel/components/tooltip";
export default function WithShortcutDemo() {
return (
);
}
```
### Stacked layout
The default `layout="single"` is a compact chip that wraps long labels within 500px and the available viewport width. Use `layout="stacked"` for short descriptions (Figma multiline); its shortcut sits under the label. Prefer a popover if the copy runs longer than about two lines.
```tsx
import { Button } from "@makeplane/propel/components/button";
import { Tooltip } from "@makeplane/propel/components/tooltip";
export default function StackedDemo() {
return (
);
}
```
### Grouped
Wrapping triggers in a `TooltipProvider` shares open/close timing, so moving between adjacent triggers shows the next tooltip immediately instead of restarting the hover delay.
```tsx
import { Button } from "@makeplane/propel/components/button";
import { Tooltip, TooltipProvider } from "@makeplane/propel/components/tooltip";
export default function GroupedDemo() {
return (
);
}
```
### Controlled
Own open state in React with `open` / `onOpenChange`. The secondary action calls `setOpen(true)`; Escape and blur still flow through `onOpenChange`, so the tooltip cannot stick open. The live “React state” label shows that ownership.
```tsx
import { Button } from "@makeplane/propel/components/button";
import { Tooltip } from "@makeplane/propel/components/tooltip";
import * as React from "react";
export default function ControlledDemo() {
const [open, setOpen] = React.useState(false);
return (
);
}
```
### Conditional tooltip
`disabled` unmounts the tooltip for a boolean condition (`disabled={!isCollapsed}` — no tip once the sidebar expands). `label` unmounts on its own when copy may be missing (`label={email}`, no `?? ""` needed) — an empty or whitespace-only string leaves the trigger with no tooltip instead of an empty popup.
```tsx
import { Button } from "@makeplane/propel/components/button";
import { Tooltip } from "@makeplane/propel/components/tooltip";
import * as React from "react";
export default function ConditionalDemo() {
const [isCollapsed, setIsCollapsed] = React.useState(true);
const email: string | undefined = undefined;
return (
);
}
```
### Imperative handle
Use when you do not want to lift `useState`. `createTooltipHandle()` lives outside the tree; pass it as `handle`, put a stable `id` on the trigger child, then call `handle.open(id)` (here, “Open tip via handle.open”). No React open state — the handle talks to Base UI directly. Calling `open` while the tooltip is gated off by `disabled` or a missing label is a no-op. Multiple detached triggers still need Base UI `Tooltip.Trigger` composition; the ready-made only mounts one trigger from `children`.
```tsx
import { Button } from "@makeplane/propel/components/button";
import { createTooltipHandle, Tooltip } from "@makeplane/propel/components/tooltip";
const SHARE_TRIGGER_ID = "docs-share-project-hint";
const shareHint = createTooltipHandle();
export default function WithHandleDemo() {
return (
);
}
```
## API Reference
`createTooltipHandle()` (from the same entry) returns a handle for imperative `open(triggerId)` /
`close()` — see [Imperative handle](#imperative-handle). It is a factory, not a component, so it has
no props table. `TooltipPopup` and `TooltipArrow` are the styled parts for hand-assembled tooltips
(graft Base UI behavior onto them via `render`).
### Tooltip
A small popup that describes the element it is attached to. Appears on hover or keyboard focus of
the trigger and is dismissed on blur, pointer-leave, or `Esc`.
Built on Base UI's tooltip, so it's accessible by default: the popup is exposed as
`role="tooltip"` and wired to the trigger. Pass the trigger as `children`, the popup copy as
`label`, and an optional `shortcut` for a dimmed visual keyboard hint.
Grafts Base UI's tooltip behavior onto propel's styled parts: `Tooltip.Root` + `Tooltip.Trigger`
+ `Tooltip.Portal` → `Tooltip.Positioner` (shared `internal/positioner`) → `TooltipPopup`, with
an optional `TooltipArrow` when `showArrow` is set. Colors come from propel's adaptive surface
tokens (`bg-layer-2` / `text-primary` / `border-subtle-1`), so the tooltip is light on light
themes and dark on dark themes, matching the Figma "Tooltip" component.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string \| null \| undefined` | — | The text shown inside the tooltip popup. `null` / `undefined` / `""` (or whitespace-only) unmounts the popup itself (children still render, unaffected) — use this instead of `label={x ?? ""}` for copy that may be missing (an email, a name). |
| `children` (required) | `ReactElement>` | — | The element the tooltip is attached to. Base UI renders the trigger as a `