Shadcn Tooltip

View as Markdown Open in ChatGPT Open in Claude

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.

Installation

1 Configure registry — once per project 
{
  "registries": {
    "@designrevision": "https://registry.designrevision.com/r/{name}.json"
  }
}

Add to your existing components.json. Requires shadcn/ui v2.3+.

2 Install the component

Packages

@radix-ui/react-tooltip
utils

Props

side = "top"
"top" | "right" | "bottom" | "left"

Which side of the trigger the tooltip opens on (on TooltipContent).

sideOffset = 0
number

Distance in px from the trigger (on TooltipContent).

delayDuration = 0
number

Hover delay in ms before showing (on Tooltip or a shared TooltipProvider).

open / onOpenChange = —
boolean / (open: boolean) => void

Controlled visibility (on Tooltip).

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.

Copied!
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.

Packages

tooltip
button

Props

No props documented yet.

Copied!
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.

Packages

tooltip
button

Props

No props documented yet.

Copied!
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.

Packages

lucide-react
tooltip
button

Props

No props documented yet.

Copied!
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.

Packages

tooltip
button
kbd

Props

No props documented yet.

Copied!
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.

Packages

tooltip
button

Props

No props documented yet.

Copied!
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.

Packages

tooltip
button

Props

No props documented yet.

Copied!
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.

Packages

tooltip
button

Props

No props documented yet.

Copied!
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>
  )
}

The Shadcn Tooltip is the hover hint — the canonical shadcn/ui tooltip built on Radix, 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 Radix Tooltip with four parts — TooltipProvider, Tooltip, TooltipTrigger, TooltipContent. The shadcn Tooltip bundles its own provider, so a single tooltip just works:

<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 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:

<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 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.

Frequently asked questions

Yes — it is the canonical shadcn/ui tooltip, built on Radix Tooltip with four parts (TooltipProvider, Tooltip, TooltipTrigger, TooltipContent) and an arrow on the content. Official ships one demo; we add sides, an icon-button toolbar, a keyboard-shortcut hint, the disabled-trigger fix, shared-provider delays, and rich content.
Not for a single tooltip — the Tooltip component already wraps its own TooltipProvider, so it works on its own. Use one shared TooltipProvider around a group when you want them to share a delayDuration (and the skip-delay behaviour, where hovering a sibling after the first shows it instantly). The Delay & shared provider example shows this.
Set side ("top" | "right" | "bottom" | "left", default "top") and sideOffset (px) on TooltipContent. Radix automatically flips the tooltip to stay in the viewport, so you set a preference. The Sides example shows all four.
Disabled elements do not fire pointer or focus events, so the trigger never activates. Wrap the disabled control in a focusable span (give it tabIndex={0}), make the span the TooltipTrigger asChild, and add pointer-events-none to the button. The Disabled trigger example is the fix.
Set delayDuration (ms) — on a single Tooltip, or on a shared TooltipProvider to apply it to a group. The shadcn default is 0 (instant). A 500–700ms delay is common so tooltips do not flash as the pointer passes over. The Delay example uses 700ms.
A Tooltip is a short, non-interactive hint shown on hover or focus — a label for an icon button, a shortcut reminder. A [Popover](/components/popover) opens on click and can hold interactive content (inputs, buttons). If the user needs to read a label, use a Tooltip; if they need to do something, use a Popover.
Not reliably — tooltips trigger on hover and keyboard focus, neither of which exists on touch. Never put essential information (or the only label) in a tooltip. Give icon buttons an aria-label so they are announced regardless, and surface anything critical in the UI itself.
DesignRevision