# Shadcn Tooltip

> Free shadcn/ui tooltip component for React — a Radix hover/focus hint with an arrow. Four sides, icon-button toolbars, keyboard-shortcut hints, the disabled-trigger fix, and shared-provider delays. The examples official shadcn never shipped.

Source: https://designrevision.com/components/tooltip

The **Shadcn Tooltip** is the hover hint — the canonical <a href="https://ui.shadcn.com/docs/components/tooltip" rel="nofollow">shadcn/ui</a> tooltip built on <a href="https://www.radix-ui.com/primitives/docs/components/tooltip" rel="nofollow">Radix</a>, a small label that appears on hover or focus with an arrow. Official ships one demo; the examples below cover the real uses — **icon-button toolbars, shortcut hints, the disabled-trigger fix, and shared-provider delays**.

## Built on Radix

Tooltip wraps <a href="https://www.radix-ui.com/primitives/docs/components/tooltip" rel="nofollow">Radix Tooltip</a> with four parts — `TooltipProvider`, `Tooltip`, `TooltipTrigger`, `TooltipContent`. The shadcn `Tooltip` **bundles its own provider**, so a single tooltip just works:

```tsx
<Tooltip>
  <TooltipTrigger asChild>
    <Button variant="outline">Hover me</Button>
  </TooltipTrigger>
  <TooltipContent>Add to library</TooltipContent>
</Tooltip>
```

Use `asChild` on the trigger so the tooltip attaches to *your* element (a button) instead of wrapping it.

## Shared provider & delay

For a **group** of tooltips, wrap them in one `TooltipProvider` and set `delayDuration` there — they share the delay, and after the first one shows, hovering a sibling shows it instantly (the skip-delay behaviour). The shadcn default is `0`; 500–700ms is common so tooltips don't flash as the pointer passes. The Delay & shared provider example uses 700ms.

## Positioning

Set `side` (`"top" | "right" | "bottom" | "left"`, default `"top"`) and `sideOffset` on `TooltipContent`; Radix flips it to stay in view. The Sides example shows all four.

## Icon-button toolbars

The number-one use is **labelling icon-only buttons** — a formatting toolbar, a row of actions. Give each button an `aria-label` (for screen readers) *and* a tooltip (for sighted hover users). The Icon buttons example is the toolbar pattern. Pair the label with a [Kbd](/components/kbd) shortcut hint when there is one (the With shortcut example).

## The disabled-trigger gotcha

A `disabled` button fires **no** pointer or focus events, so the tooltip never opens. The fix: wrap the control in a focusable `span` (the real trigger) and turn off the button's pointer events:

```tsx
<TooltipTrigger asChild>
  <span tabIndex={0} className="inline-block">
    <Button disabled className="pointer-events-none">Submit</Button>
  </span>
</TooltipTrigger>
```

The Disabled trigger example implements it.

## Tooltip vs Popover

A **Tooltip** is a short, non-interactive hint on hover/focus. A [Popover](/components/popover) opens on click and holds interactive content. Reading a label → Tooltip; doing something → Popover.

## Accessibility & theming

Tooltips trigger on **hover and keyboard focus** — there is no touch equivalent, so **never** put essential information (or an icon button's only label) in a tooltip; use `aria-label` for that. Radix manages the timing, focus, and Escape-to-dismiss. The tooltip reads your design tokens — it uses `--foreground` / `--background` for the dark pill — so it follows your theme, including dark mode, with no overrides. The open/close animation comes from `tw-animate-css`.

## Installation

### tooltip

**Install:**

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

**Dependencies:** @radix-ui/react-tooltip, utils

**Props**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| side | "top" \| "right" \| "bottom" \| "left" | "top" | Which side of the trigger the tooltip opens on (on TooltipContent). |
| sideOffset | number | 0 | Distance in px from the trigger (on TooltipContent). |
| delayDuration | number | 0 | Hover delay in ms before showing (on Tooltip or a shared TooltipProvider). |
| open / onOpenChange | boolean / (open: boolean) => void | — | Controlled visibility (on Tooltip). |

**Usage & accessibility:** A Radix tooltip — four parts (TooltipProvider, Tooltip, TooltipTrigger, TooltipContent). Tooltip already bundles a TooltipProvider, so a single tooltip works on its own; wrap a group in one shared TooltipProvider to share delayDuration. TooltipContent renders an arrow. Tooltips fire on hover and focus only — for a disabled trigger, wrap it in a span; never put essential info in a tooltip.

```tsx
// components/ui/tooltip.tsx
"use client"

import * as React from "react"
import * as TooltipPrimitive from "@radix-ui/react-tooltip"

import { cn } from "@/lib/utils"

function TooltipProvider({
  delayDuration = 0,
  ...props
}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
  return (
    <TooltipPrimitive.Provider
      data-slot="tooltip-provider"
      delayDuration={delayDuration}
      {...props}
    />
  )
}

function Tooltip({
  ...props
}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
  return (
    <TooltipProvider>
      <TooltipPrimitive.Root data-slot="tooltip" {...props} />
    </TooltipProvider>
  )
}

function TooltipTrigger({
  ...props
}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
}

function TooltipContent({
  className,
  sideOffset = 0,
  children,
  ...props
}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
  return (
    <TooltipPrimitive.Portal>
      <TooltipPrimitive.Content
        data-slot="tooltip-content"
        sideOffset={sideOffset}
        className={cn(
          "bg-foreground text-background animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-fit origin-(--radix-tooltip-content-transform-origin) rounded-md px-3 py-1.5 text-xs text-balance",
          className
        )}
        {...props}
      >
        {children}
        <TooltipPrimitive.Arrow className="bg-foreground fill-foreground z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px]" />
      </TooltipPrimitive.Content>
    </TooltipPrimitive.Portal>
  )
}

export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }
```

## Examples

### Tooltip

The canonical tooltip — a hover/focus hint on a button, with an arrow.

**Install:**

```bash
npx shadcn@latest add @designrevision/tooltip-demo-01
```

**Dependencies:** tooltip, button

```tsx
// components/ui/tooltip-demo-01.tsx
import { Button } from "@/components/ui/button"
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@/components/ui/tooltip"

export default function TooltipDemo01() {
  return (
    <Tooltip>
      <TooltipTrigger asChild>
        <Button variant="outline">Hover me</Button>
      </TooltipTrigger>
      <TooltipContent>
        <p>Add to library</p>
      </TooltipContent>
    </Tooltip>
  )
}
```

---

### Sides

Open from any side of the trigger — `top`, `right`, `bottom`, or `left` — with the `side` prop.

**Install:**

```bash
npx shadcn@latest add @designrevision/tooltip-sides-01
```

**Dependencies:** tooltip, button

```tsx
// components/ui/tooltip-sides-01.tsx
import { Button } from "@/components/ui/button"
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@/components/ui/tooltip"

const sides = ["top", "right", "bottom", "left"] as const

export default function TooltipSides01() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      {sides.map((side) => (
        <Tooltip key={side}>
          <TooltipTrigger asChild>
            <Button variant="outline" className="capitalize">
              {side}
            </Button>
          </TooltipTrigger>
          <TooltipContent side={side}>
            <p>On the {side}</p>
          </TooltipContent>
        </Tooltip>
      ))}
    </div>
  )
}
```

---

### Icon buttons

A toolbar of icon-only [buttons](/components/button), each labelled by a tooltip — the most common real use.

**Install:**

```bash
npx shadcn@latest add @designrevision/tooltip-icon-01
```

**Dependencies:** lucide-react, tooltip, button

```tsx
// components/ui/tooltip-icon-01.tsx
import { BoldIcon, ItalicIcon, LinkIcon, UnderlineIcon } from "lucide-react"

import { Button } from "@/components/ui/button"
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@/components/ui/tooltip"

const tools = [
  { icon: BoldIcon, label: "Bold" },
  { icon: ItalicIcon, label: "Italic" },
  { icon: UnderlineIcon, label: "Underline" },
  { icon: LinkIcon, label: "Insert link" },
]

export default function TooltipIcon01() {
  return (
    <div className="flex items-center gap-1 rounded-md border p-1">
      {tools.map((tool) => (
        <Tooltip key={tool.label}>
          <TooltipTrigger asChild>
            <Button variant="ghost" size="icon" aria-label={tool.label}>
              <tool.icon />
            </Button>
          </TooltipTrigger>
          <TooltipContent>{tool.label}</TooltipContent>
        </Tooltip>
      ))}
    </div>
  )
}
```

---

### With shortcut

A tooltip pairing the label with a [Kbd](/components/kbd) keyboard-shortcut hint.

**Install:**

```bash
npx shadcn@latest add @designrevision/tooltip-shortcut-01
```

**Dependencies:** tooltip, button, kbd

```tsx
// components/ui/tooltip-shortcut-01.tsx
import { Button } from "@/components/ui/button"
import { Kbd } from "@/components/ui/kbd"
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@/components/ui/tooltip"

export default function TooltipShortcut01() {
  return (
    <Tooltip>
      <TooltipTrigger asChild>
        <Button variant="outline">Save</Button>
      </TooltipTrigger>
      <TooltipContent className="flex items-center gap-2">
        Save changes
        <Kbd className="bg-background/20 text-background border-transparent">
          ⌘S
        </Kbd>
      </TooltipContent>
    </Tooltip>
  )
}
```

---

### Disabled trigger

The classic gotcha — a disabled element fires no events, so wrap it in a focusable `span` to keep the tooltip.

**Install:**

```bash
npx shadcn@latest add @designrevision/tooltip-disabled-01
```

**Dependencies:** tooltip, button

```tsx
// components/ui/tooltip-disabled-01.tsx
import { Button } from "@/components/ui/button"
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@/components/ui/tooltip"

export default function TooltipDisabled01() {
  return (
    <Tooltip>
      <TooltipTrigger asChild>
        {/*
          A disabled element fires no pointer events, so the tooltip never
          opens. Wrap it in a focusable span (the real trigger) and turn off
          pointer events on the button itself.
        */}
        <span tabIndex={0} className="inline-block">
          <Button variant="outline" disabled className="pointer-events-none">
            Submit
          </Button>
        </span>
      </TooltipTrigger>
      <TooltipContent>
        <p>Complete all required fields to submit</p>
      </TooltipContent>
    </Tooltip>
  )
}
```

---

### Delay & shared provider

One `TooltipProvider` sets a hover delay for a whole group; siblings then show instantly after the first.

**Install:**

```bash
npx shadcn@latest add @designrevision/tooltip-delay-01
```

**Dependencies:** tooltip, button

```tsx
// components/ui/tooltip-delay-01.tsx
import { Button } from "@/components/ui/button"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"

const items = ["Home", "Projects", "Settings"]

export default function TooltipDelay01() {
  return (
    // One shared provider sets the hover delay for the whole group; once one
    // tooltip has shown, hovering its siblings shows them instantly.
    <TooltipProvider delayDuration={700}>
      <div className="flex items-center gap-3">
        {items.map((item) => (
          <Tooltip key={item}>
            <TooltipTrigger asChild>
              <Button variant="outline">{item}</Button>
            </TooltipTrigger>
            <TooltipContent>Open {item}</TooltipContent>
          </Tooltip>
        ))}
      </div>
    </TooltipProvider>
  )
}
```

---

### Rich content

A wider tooltip with a title and a description line for a richer hint.

**Install:**

```bash
npx shadcn@latest add @designrevision/tooltip-rich-01
```

**Dependencies:** tooltip, button

```tsx
// components/ui/tooltip-rich-01.tsx
import { Button } from "@/components/ui/button"
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@/components/ui/tooltip"

export default function TooltipRich01() {
  return (
    <Tooltip>
      <TooltipTrigger asChild>
        <Button variant="outline">Storage</Button>
      </TooltipTrigger>
      <TooltipContent className="max-w-[220px]">
        <p className="font-medium">Storage almost full</p>
        <p className="text-background/80 mt-1">
          You&apos;ve used 9.2 GB of your 10 GB. Upgrade or remove files to free
          up space.
        </p>
      </TooltipContent>
    </Tooltip>
  )
}
```