---
title: Tooltip
description: A popup that appears when an element is hovered or focused, showing a hint for sighted users.
icon: info
author:
  name: imskyleen
  url: https://github.com/imskyleen
search:
  keywords: [hint, title]
related:
  - /hover-card
  - /popover
mode: wide
---

<PoweredBy
  packages={[
    { name: 'Base UI', url: 'https://base-ui.com/react/components/tooltip' },
    { name: 'Shadcn UI', url: 'https://ui.shadcn.com/docs/components/tooltip' },
  ]}
/>

### Installation

```package-install
npx shadcn@latest add @redpanda/tooltip
```

<ComponentPreview name="tooltip-demo" description="Default tooltip on a button — opens on hover or keyboard focus." />

### Positioning

<ComponentPreview
  name="tooltip-side-demo"
  description="Render the tooltip on any side (top / right / bottom / left) via the `side` prop."
/>

## When to use

Tooltips are supplementary visual labels for controls that already have an independent purpose and accessible
name. They are not a way to deliver instructions to touch or screen reader users.

```mermaid
graph TD;
    A[What is the trigger for?] --> B{Opening information?};
    B --> |Yes| C[Use Popover];
    B --> |No| D{Supplementary visual label?};
    D --> |Yes| E[Use Tooltip with a matching trigger name];
    D --> |No| F[Use a visible label or description];
```

If an information icon exists to open its own popup, use [Popover](/docs/popover) with a named title and description.
`openOnHover` on `PopoverTrigger` can retain optional hover access while native activation works with keyboard
and touch. Keep essential field instructions visible and associate them with the input using `aria-describedby`.

See the [Base UI usage guidelines](https://base-ui.com/react/components/tooltip#usage-guidelines) and
[infotip guidance](https://base-ui.com/react/components/tooltip#infotips).

## Usage

```tsx
<TooltipProvider>
  <Tooltip>
    <TooltipTrigger render={<Button type="submit">Save</Button>} />
    <TooltipContent>Save</TooltipContent>
  </Tooltip>
</TooltipProvider>
```

## Props

<div className="flex flex-row gap-x-3">
  <ExternalLink href="https://base-ui.com/react/components/tooltip" text="Docs" />
  <ExternalLink href="https://base-ui.com/react/components/tooltip#api-reference" text="API Reference" />
</div>

### Props

#### TooltipContent

| Prop | Type | Default | Description |
| - | - | - | - |
| `arrow?` | `boolean` | `true` | Whether to show the arrow. |

## Keyboard interactions

| Key                         | Action                                                    |
| --------------------------- | --------------------------------------------------------- |
| `Tab` to `TooltipTrigger`   | Opens the tooltip (keyboard-focus trigger).               |
| `Shift+Tab` off the trigger | Closes the tooltip.                                       |
| `Escape`                    | Closes the tooltip without moving focus.                  |
| Mouse hover / blur          | Opens after `delayDuration`, closes immediately on leave. |

## Accessibility

- Tooltips are **visual-only** hints. They do not provide `aria-describedby` or replace the trigger's accessible name.
  Give icon controls an `aria-label` that closely matches the visible hint.
- Use a native interactive trigger through `render`. Keep its original action and keyboard behavior; do not add a
  focusable wrapper solely to expose a disabled control's reason. Put important reasons in associated visible text.
- Use [Popover](/docs/popover), not Tooltip, when opening information is the trigger's purpose. Give the popover a
  `PopoverTitle` and `PopoverDescription`; native activation must work without hover.
- Wrap multiple tooltips in a single `TooltipProvider` — Base UI shares a `delay` / `timeout` pool so rapid-hover
  tooltips don't re-fire the delay.

## Controlled vs uncontrolled

Uncontrolled — typical case:

```tsx lineNumbers
<Tooltip>
  <TooltipTrigger render={<Button type="submit">Save</Button>} />
  <TooltipContent>Save</TooltipContent>
</Tooltip>
```

Controlled — coordinate the visibility of a visual hint; this does not announce new information to assistive technology:

```tsx lineNumbers
const [open, setOpen] = useState(true);

<Tooltip open={open} onOpenChange={setOpen}>
  <TooltipTrigger render={<Button type="submit">Save</Button>} />
  <TooltipContent>Save</TooltipContent>
</Tooltip>;
```

## Credits

- We use [Base UI](https://base-ui.com/react/components/tooltip) for the tooltip component.
- We take our inspiration from [Shadcn UI](https://ui.shadcn.com/docs/components/tooltip) for the tooltip style.