Tooltip

import { BookmarkPlusIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Tooltip, TooltipTrigger } from "@/components/ui/tooltip";

export default function TooltipDemo() {
  return (
    <TooltipTrigger>
      <Button variant="outline" size="icon" aria-label="Add to library">
        <BookmarkPlusIcon />
      </Button>
      <Tooltip>Add to library</Tooltip>
    </TooltipTrigger>
  );
}

Installation

$ pnpm dlx shadcn@latest add @desyne/tooltip

The CLI installs dependencies and any other components this one uses.

Usage

tsx

import { Tooltip, TooltipTrigger } from "@/components/ui/tooltip";

tsx

<TooltipTrigger>
  <Button variant="ghost" size="icon" aria-label="Save">
    <SaveIcon />
  </Button>
  <Tooltip>Save</Tooltip>
</TooltipTrigger>

TooltipTrigger wraps a focusable trigger (a Button, Link, ToggleButton or any element inside React Aria's Focusable) and the Tooltip that describes it.

Tooltips supplement, they don't replace labels

The tooltip is linked to its trigger with aria-describedby, so it's read as a description after the trigger's name. Icon-only buttons still need an aria-label. Touch users never see tooltips, so don't put essential information or interactive content in them; use a Popover instead.

When to use

Tooltip — a brief label or hint for a control, especially icon-only buttons, abbreviations and truncated text.
Popover — interactive content, or anything users need to read on touch devices.
Inline help text (a field description) — guidance that should always be visible.
Toast — feedback about something that just happened.

Anatomy

tsx

<TooltipTrigger>          {/* hover, focus and delay handling */}
  <Button />              {/* focusable trigger */}
  <Tooltip>               {/* role="tooltip", optional arrow */}
    Label
  </Tooltip>
</TooltipTrigger>

Part	Renders	Notes
`TooltipTrigger`	—	Opens the tooltip on hover (after `delay`) or keyboard focus (immediately). Defaults to a 400ms open and 100ms close delay.
`Tooltip`	`<div role="tooltip">` (portal)	The positioned bubble. Carries `data-slot="tooltip"`.
Arrow	`OverlayArrow` › `<svg>`	8px arrow pointing at the trigger. Rendered unless `showArrow={false}`.

Examples

Placement

placement accepts top (default), bottom, left, right, start, end and combinations like top start. The tooltip flips to the opposite side when there isn't room, and the arrow rotates with it.

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

const placements = ["top", "right", "bottom", "left"] as const;

export default function TooltipPlacement() {
  return (
    <div className="flex flex-wrap gap-2">
      {placements.map((placement) => (
        <TooltipTrigger key={placement}>
          <Button variant="outline" className="capitalize">
            {placement}
          </Button>
          <Tooltip placement={placement}>Tooltip on {placement}</Tooltip>
        </TooltipTrigger>
      ))}
    </div>
  );
}

Light variant

variant="light" renders a bordered card that matches popovers. Use it for two-line content, like a metric name and its definition. Tooltips are capped at max-w-xs; pass a max-w-* class for a narrower measure.

import { InfoIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Tooltip, TooltipTrigger } from "@/components/ui/tooltip";

export default function TooltipLight() {
  return (
    <TooltipTrigger>
      <Button variant="ghost" size="icon" aria-label="What is MTTR?">
        <InfoIcon />
      </Button>
      <Tooltip variant="light" className="max-w-56">
        <p className="font-medium">Mean time to resolve</p>
        <p className="mt-0.5 text-muted-foreground">
          Average time from an alert firing to the incident being closed.
        </p>
      </Tooltip>
    </TooltipTrigger>
  );
}

Without arrow

showArrow={false} hides the arrow. Drop the offset to keep the tooltip close to dense toolbars.

import { DownloadIcon, PrinterIcon, Share2Icon } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Tooltip, TooltipTrigger } from "@/components/ui/tooltip";

const actions = [
  { label: "Download", icon: DownloadIcon },
  { label: "Print", icon: PrinterIcon },
  { label: "Share", icon: Share2Icon },
];

export default function TooltipNoArrow() {
  return (
    <div className="flex items-center gap-1">
      {actions.map((a) => (
        <TooltipTrigger key={a.label}>
          <Button variant="ghost" size="icon" aria-label={a.label}>
            <a.icon />
          </Button>
          <Tooltip showArrow={false} placement="bottom" offset={4}>
            {a.label}
          </Tooltip>
        </TooltipTrigger>
      ))}
    </div>
  );
}

With keyboard shortcut

Tooltips are a natural place to advertise shortcuts. Put a Kbd in the content; the light variant keeps it legible.

import { RedoIcon, SearchIcon, UndoIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Kbd, KbdGroup } from "@/components/ui/kbd";
import { Tooltip, TooltipTrigger } from "@/components/ui/tooltip";

const actions = [
  { label: "Undo", icon: UndoIcon, keys: ["⌘", "Z"] },
  { label: "Redo", icon: RedoIcon, keys: ["⌘", "⇧", "Z"] },
  { label: "Search", icon: SearchIcon, keys: ["⌘", "K"] },
];

export default function TooltipWithKbd() {
  return (
    <div className="flex items-center gap-1">
      {actions.map((a) => (
        <TooltipTrigger key={a.label}>
          <Button variant="ghost" size="icon" aria-label={a.label}>
            <a.icon />
          </Button>
          <Tooltip variant="light" className="flex items-center gap-2">
            {a.label}
            <KbdGroup>
              {a.keys.map((k) => (
                <Kbd key={k} size="sm">
                  {k}
                </Kbd>
              ))}
            </KbdGroup>
          </Tooltip>
        </TooltipTrigger>
      ))}
    </div>
  );
}

Delay

delay and closeDelay on TooltipTrigger set how long hover waits before opening and closing. Once one tooltip has opened, moving to a nearby trigger opens the next one immediately. Keyboard focus always opens without delay.

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

export default function TooltipDelay() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <TooltipTrigger delay={0}>
        <Button variant="outline">Instant</Button>
        <Tooltip>Opens immediately</Tooltip>
      </TooltipTrigger>
      <TooltipTrigger>
        <Button variant="outline">Default</Button>
        <Tooltip>Opens after 400ms</Tooltip>
      </TooltipTrigger>
      <TooltipTrigger delay={1200} closeDelay={600}>
        <Button variant="outline">Slow</Button>
        <Tooltip>Opens after 1.2s, lingers for 600ms</Tooltip>
      </TooltipTrigger>
    </div>
  );
}

Focus only

trigger="focus" shows the tooltip for keyboard focus only, not on hover. Use it for hints that would be noisy under the mouse.

Coupon code

import { Button } from "@/components/ui/button";
import { TextField } from "@/components/ui/text-field";
import { Tooltip, TooltipTrigger } from "@/components/ui/tooltip";

export default function TooltipFocusTrigger() {
  return (
    <div className="flex items-end gap-2">
      <TextField label="Coupon code" placeholder="SPRING26" className="w-48" />
      <TooltipTrigger trigger="focus">
        <Button variant="outline">Apply</Button>
        <Tooltip placement="bottom">Codes are case-insensitive</Tooltip>
      </TooltipTrigger>
    </div>
  );
}

Controlled

isOpen and onOpenChange on TooltipTrigger let you open the tooltip from code, like confirming a copy action. shouldCloseOnPress={false} keeps it open while the trigger is pressed.

npm i @acme/sdk

import { CheckIcon, CopyIcon } from "lucide-react";
import { useState } from "react";
import { Button } from "@/components/ui/button";
import { Tooltip, TooltipTrigger } from "@/components/ui/tooltip";

export default function TooltipControlled() {
  const [isOpen, setOpen] = useState(false);
  const [copied, setCopied] = useState(false);

  const copy = async () => {
    await navigator.clipboard?.writeText("npm i @acme/sdk").catch(() => {});
    setCopied(true);
    setOpen(true);
    setTimeout(() => {
      setCopied(false);
      setOpen(false);
    }, 1500);
  };

  return (
    <div className="flex items-center gap-2 rounded-lg border bg-muted/40 py-1 pr-1 pl-3 font-mono text-sm">
      npm i @acme/sdk
      <TooltipTrigger
        isOpen={isOpen}
        onOpenChange={setOpen}
        shouldCloseOnPress={false}
      >
        <Button
          variant="ghost"
          size="icon-sm"
          aria-label="Copy command"
          onPress={copy}
        >
          {copied ? <CheckIcon className="text-success" /> : <CopyIcon />}
        </Button>
        <Tooltip>{copied ? "Copied!" : "Copy command"}</Tooltip>
      </TooltipTrigger>
    </div>
  );
}

Disabling tooltips

isDisabled on TooltipTrigger turns the tooltip off without touching the trigger. Here tooltips only appear while the navigation is collapsed to icons. Disabled buttons never show tooltips, since they don't receive hover or focus.

Show labels

import { FolderIcon, HomeIcon, InboxIcon } from "lucide-react";
import { useState } from "react";
import { Button } from "@/components/ui/button";
import { Switch } from "@/components/ui/switch";
import { Tooltip, TooltipTrigger } from "@/components/ui/tooltip";

const items = [
  { label: "Home", icon: HomeIcon },
  { label: "Inbox", icon: InboxIcon },
  { label: "Projects", icon: FolderIcon },
];

export default function TooltipDisabled() {
  const [expanded, setExpanded] = useState(false);
  return (
    <div className="flex flex-col items-start gap-4">
      <Switch isSelected={expanded} onChange={setExpanded}>
        Show labels
      </Switch>
      <nav
        aria-label="Main"
        className="flex flex-col gap-1 rounded-lg border bg-card p-1"
      >
        {items.map((item) => (
          <TooltipTrigger key={item.label} isDisabled={expanded}>
            <Button
              variant="ghost"
              size={expanded ? "md" : "icon"}
              aria-label={expanded ? undefined : item.label}
              className={expanded ? "w-32 justify-start" : undefined}
            >
              <item.icon />
              {expanded && item.label}
            </Button>
            <Tooltip placement="right">{item.label}</Tooltip>
          </TooltipTrigger>
        ))}
      </nav>
    </div>
  );
}

Custom trigger

Wrap non-interactive elements in React Aria's Focusable so they can own a tooltip. The child needs tabIndex={0} and an ARIA role (button, img, link and similar), and must forward its ref.

Median latency (p50) dropped to 182 ms this week −12%

import { Focusable } from "react-aria-components";
import { Badge } from "@/components/ui/badge";
import { Tooltip, TooltipTrigger } from "@/components/ui/tooltip";

const focusRing =
  "cursor-help rounded-xs outline-none focus-visible:ring-[3px] focus-visible:ring-ring/25";

export default function TooltipCustomTrigger() {
  return (
    <p className="max-w-sm text-sm leading-relaxed">
      Median latency (
      <TooltipTrigger>
        <Focusable>
          {/* biome-ignore lint/a11y/useSemanticElements: inline term, not a button */}
          <span
            role="button"
            tabIndex={0}
            className={`${focusRing} underline decoration-dotted underline-offset-4`}
          >
            p50
          </span>
        </Focusable>
        <Tooltip>50th percentile: half of all requests were faster</Tooltip>
      </TooltipTrigger>
      ) dropped to 182 ms this week{" "}
      <TooltipTrigger>
        <Focusable>
          <span
            role="img"
            aria-label="Down 12%"
            // biome-ignore lint/a11y/noNoninteractiveTabindex: focusable so keyboard users get the tooltip
            tabIndex={0}
            className={focusRing}
          >
            <Badge size="sm" color="success">
              −12%
            </Badge>
          </span>
        </Focusable>
        <Tooltip>Compared with the previous 7 days</Tooltip>
      </TooltipTrigger>
    </p>
  );
}

Recipes

An icon rail with right-side tooltips that show each destination and its shortcut. delay={0} makes scanning the rail instant.

import {
  BarChart3Icon,
  HomeIcon,
  InboxIcon,
  LayersIcon,
  SettingsIcon,
} from "lucide-react";
import { Button } from "@/components/ui/button";
import { Kbd } from "@/components/ui/kbd";
import { Tooltip, TooltipTrigger } from "@/components/ui/tooltip";
import { cn } from "@/lib/utils";

const items = [
  { label: "Home", icon: HomeIcon, kbd: "G H", current: true },
  { label: "Inbox", icon: InboxIcon, kbd: "G I" },
  { label: "Projects", icon: LayersIcon, kbd: "G P" },
  { label: "Analytics", icon: BarChart3Icon, kbd: "G A" },
];

export default function TooltipRecipeIconRail() {
  return (
    <nav
      aria-label="Main"
      className="flex h-72 w-14 flex-col items-center gap-1 rounded-xl border bg-card py-3"
    >
      <div className="mb-3 size-7 rounded-lg bg-brand" aria-hidden />
      {items.map((item) => (
        <TooltipTrigger key={item.label} delay={0}>
          <Button
            variant="ghost"
            size="icon"
            aria-label={item.label}
            aria-current={item.current ? "page" : undefined}
            className={cn(item.current && "bg-muted text-foreground")}
          >
            <item.icon />
          </Button>
          <Tooltip placement="right" className="flex items-center gap-2">
            {item.label}
            <Kbd
              size="sm"
              className="border-background/20 bg-background/15 text-background"
            >
              {item.kbd}
            </Kbd>
          </Tooltip>
        </TooltipTrigger>
      ))}
      <TooltipTrigger delay={0}>
        <Button
          variant="ghost"
          size="icon"
          aria-label="Settings"
          className="mt-auto"
        >
          <SettingsIcon />
        </Button>
        <Tooltip placement="right">Settings</Tooltip>
      </TooltipTrigger>
    </nav>
  );
}

Avatar stack

Overlapping Avatars, each wrapped in Focusable with role="img" and a name, show who has access on hover or focus.

4 collaborators

import { Focusable } from "react-aria-components";
import { Avatar } from "@/components/ui/avatar";
import { Tooltip, TooltipTrigger } from "@/components/ui/tooltip";

const people = [
  { name: "Amara Okafor", role: "Owner", initials: "AO" },
  { name: "Ben Carter", role: "Editor", initials: "BC" },
  { name: "Chloé Martin", role: "Editor", initials: "CM" },
  { name: "Dev Patel", role: "Viewer", initials: "DP" },
];

export default function TooltipRecipeAvatarStack() {
  return (
    <div className="flex items-center gap-3">
      <ul aria-label="People with access" className="flex -space-x-2">
        {people.map((p) => (
          <li key={p.name}>
            <TooltipTrigger delay={200}>
              <Focusable>
                <span
                  role="img"
                  aria-label={p.name}
                  // biome-ignore lint/a11y/noNoninteractiveTabindex: focusable so keyboard users get the tooltip
                  tabIndex={0}
                  className="block rounded-full outline-none ring-2 ring-background focus-visible:ring-ring/50"
                >
                  <Avatar alt={p.name} fallback={p.initials} colorful />
                </span>
              </Focusable>
              <Tooltip variant="light">
                <p className="font-medium">{p.name}</p>
                <p className="text-muted-foreground">{p.role}</p>
              </Tooltip>
            </TooltipTrigger>
          </li>
        ))}
      </ul>
      <span className="text-muted-foreground text-sm">4 collaborators</span>
    </div>
  );
}

Metric definitions

KPI cards with an info button next to each label. The light variant holds the metric's name and a short definition.

Net revenue retention

118%

+4.2 pts vs last quarter

Payback period

11.4 mo

−0.8 mo vs last quarter

import { InfoIcon, TrendingUpIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Tooltip, TooltipTrigger } from "@/components/ui/tooltip";

const metrics = [
  {
    label: "Net revenue retention",
    value: "118%",
    delta: "+4.2 pts",
    help: "Revenue this month from customers who were active 12 months ago, divided by their revenue back then. Includes expansion, contraction and churn.",
  },
  {
    label: "Payback period",
    value: "11.4 mo",
    delta: "−0.8 mo",
    help: "Months of gross margin needed to recover the cost of acquiring a customer.",
  },
];

export default function TooltipRecipeMetricCard() {
  return (
    <div className="grid w-full max-w-lg gap-3 sm:grid-cols-2">
      {metrics.map((m) => (
        <div key={m.label} className="rounded-xl border bg-card p-4">
          <div className="flex items-center gap-1 text-muted-foreground text-sm">
            {m.label}
            <TooltipTrigger delay={200}>
              <Button
                variant="ghost"
                size="icon-xs"
                aria-label={`About ${m.label}`}
              >
                <InfoIcon />
              </Button>
              <Tooltip
                variant="light"
                placement="top start"
                className="max-w-64"
              >
                <p className="font-medium text-foreground">{m.label}</p>
                <p className="mt-1 text-muted-foreground">{m.help}</p>
              </Tooltip>
            </TooltipTrigger>
          </div>
          <p className="mt-2 font-semibold text-2xl tabular-nums">{m.value}</p>
          <p className="mt-1 flex items-center gap-1 text-success text-xs">
            <TrendingUpIcon className="size-3.5" /> {m.delta} vs last quarter
          </p>
        </div>
      ))}
    </div>
  );
}

Accessibility

The tooltip has role="tooltip" and is linked to its trigger with aria-describedby, so screen readers read it after the trigger's name.
It opens on hover after delay, and immediately when the trigger receives keyboard focus. It doesn't open for touch.
It closes on Esc, when the pointer leaves (after closeDelay), when focus moves away, and when the trigger is pressed (unless shouldCloseOnPress={false}).
Keep tooltip content short and non-interactive. Anything focusable inside a tooltip can't be reached.
The trigger must be focusable. Wrap plain elements in Focusable with a tabIndex and a role.

Keyboard

Key	Action
`Tab`	Focusing the trigger opens the tooltip
`Esc`	Hides the tooltip

Styling

Data attributes

On the Tooltip:

Attribute	Present when
`data-placement`	Always: the resolved side, `"top"`, `"bottom"`, `"left"` or `"right"`
`data-entering`	Opening animation is running
`data-exiting`	Closing animation is running
`data-slot="tooltip"`	Always

The enter animation fades, zooms and slides in from the trigger's side based on data-placement.

Customizing

className on Tooltip styles the bubble: it's w-fit max-w-xs rounded-md px-2.5 py-1.5 text-xs with text-balance. Pass max-w-* or padding classes to change it, or flex items-center gap-2 to lay out rich content.
The default variant uses bg-foreground text-background, so it inverts with the theme; light uses bg-popover with a border.
The arrow's fill follows the variant. When overriding the background, hide the arrow or restyle it via [&_svg]:fill-….
--trigger-anchor-point is set on the tooltip, for a custom transform-origin.

Render props

className and children accept a function of the tooltip's state:

tsx

<Tooltip className={({ placement }) => (placement === "bottom" ? "mt-1" : "")}>
  Label
</Tooltip>

API Reference

TooltipTrigger

Prop

Type

Also accepts every prop of React Aria's TooltipTrigger.

Prop

Type

Also accepts every prop of React Aria's Tooltip.

Popover — interactive content anchored to a trigger.
Button — icon-only buttons are the most common tooltip trigger.
Kbd — show shortcuts inside tooltips.
Toggle Button — label icon-only toggles with a tooltip.