---
title: Tooltip
description: A popup that appears when an element is hovered or focused, showing a hint for sighted users.

links:
  doc: https://base-ui.com/react/components/tooltip#api-reference
---

<ComponentPreview name="p-tooltip-1" />

## Installation

<CodeTabs>

<TabsList>
  <TabsTab value="cli">CLI</TabsTab>
  <TabsTab value="manual">Manual</TabsTab>
</TabsList>
<TabsPanel value="cli">

```bash
npx shadcn@latest add @coss/tooltip
```

</TabsPanel>

<TabsPanel value="manual">

<Steps>

<Step>Install the following dependencies:</Step>

```bash
npm install @base-ui/react
```

<Step>Copy and paste the following code into your project.</Step>

<ComponentSource name="tooltip" title="components/ui/tooltip.tsx" />

<Step>Update the import paths to match your project setup.</Step>

</Steps>

</TabsPanel>

</CodeTabs>

## Usage

```tsx
import {
  Tooltip,
  TooltipCreateHandle,
  TooltipPopup,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"
```

```tsx
<Tooltip>
  <TooltipTrigger render={<Button variant="outline" />}>
    Hover me
  </TooltipTrigger>
  <TooltipPopup>Helpful hint</TooltipPopup>
</Tooltip>
```

## API Reference

### Tooltip

Root component. Alias for `Tooltip.Root` from Base UI.

### TooltipTrigger

Trigger element that shows the tooltip on hover/focus. Alias for `Tooltip.Trigger` from Base UI.

### TooltipPopup

Popup container that displays the tooltip content. Also exported as `TooltipContent`.

| Prop         | Type                                     | Default    | Description                                      |
| ------------ | ---------------------------------------- | ---------- | ------------------------------------------------ |
| `side`       | `"top" \| "bottom" \| "left" \| "right"` | `"top"`    | Side of the trigger to position the tooltip      |
| `align`      | `"start" \| "center" \| "end"`           | `"center"` | Alignment relative to the trigger                |
| `sideOffset` | `number`                                 | `4`        | Distance from the trigger in pixels              |
| `portalProps` | `Tooltip.Portal.Props`                  | -          | Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Tooltip portal API |

### TooltipProvider

Provider for grouping tooltips. Alias for `Tooltip.Provider` from Base UI.

### TooltipCreateHandle

Creates a handle for detached tooltip triggers. Returns a handle object to attach to multiple triggers for animated transitions.

## Examples

### Grouped Tooltips

To group multiple tooltips so they appear instantly after the first one is opened, wrap them in `TooltipProvider`. The grouping logic ensures that once a tooltip becomes visible, the adjacent tooltips will be shown instantly.

<ComponentPreview name="p-tooltip-2" />

### Animated Tooltips

You can create animated tooltips that smoothly transition between different triggers using detached triggers. This pattern allows multiple triggers to share a single tooltip popup, with automatic animations for position, size, and content changes.

To create detached triggers:

1. Create a handle using `TooltipCreateHandle`
2. Attach the same handle to multiple `TooltipTrigger` components
3. Each trigger provides a `payload` prop containing the content component
4. Use a single `Tooltip` component with the handle to render the popup

<ComponentPreview name="p-tooltip-3" />