Tooltip

A tooltip shows a short, non-interactive label on hover or focus. Use it to name icon-only buttons or add a brief hint; for anything clickable or longer than a phrase, use Popover instead.

Preview

Installation

npx shadcn@latest add @cubby-ui/tooltip

Usage

import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/cubby-ui/tooltip";

<TooltipProvider>
  <Tooltip>
    <TooltipTrigger />
    <TooltipContent />
  </Tooltip>
</TooltipProvider>

Composition

Tooltip
├── TooltipTrigger
└── TooltipContent

TooltipContent composes the portal, positioner, popup, and optional arrow internally, so you pass your label directly inside it. Wrap your app in TooltipProvider to share open and close timing across tooltips.

Timing

Three props control when a tooltip appears and disappears.

timeout is what makes a row of icon buttons feel responsive: hover the first, then move along the row, and the rest appear with no wait. It only applies inside a TooltipProvider, which is why every example here is wrapped in one.

<TooltipProvider delay={400} closeDelay={100} timeout={600}>
  {/* every tooltip below shares this timing */}
</TooltipProvider>

Set delay on an individual TooltipTrigger to override the provider for one tooltip. A trigger-level delay always wins, so leave it unset when you want the provider's value.

<TooltipTrigger delay={0}>Opens immediately</TooltipTrigger>

Without a TooltipProvider there is no shared timing and no instant-reopen window, and Base UI's own 600 delay applies unless you set one per trigger.

Examples

Chrome Surface

Set variant="chrome" for a near-black tooltip in both light and dark. Use it for labels that belong to persistent app chrome, like a header bar or a floating toolbar, where a tooltip that borrows the page surface reads as part of the page rather than part of the control.

The chrome surface sits off the elevation ladder, so level and shadowLevel have no effect on it. It also carries no edge: the chrome edge is an opt-in shadow-(--chrome-shadow) that larger containers add, and on a label two lines tall it is more boundary than there is object. A tooltip already carries its shape through its text and arrow.

It brings its own palette with it: text, muted text, borders, form-field fills and hover washes inside the tooltip resolve against the dark fill, so ordinary classes like text-muted-foreground keep working.

<TooltipContent variant="chrome">
  <p>Notifications</p>
  <p className="text-muted-foreground">Reads correctly on the dark fill</p>
</TooltipContent>

The same surface is available to your own containers. Put data-surface="chrome" on any element and use bg-chrome for the fill, and everything inside paints against it with no per-control classes.

Detached Trigger

Use createTooltipHandle() to link a trigger outside the Tooltip component.

Controlled

Control the tooltip's open state externally using the open and onOpenChange props.

Animated Transitions

Animate the tooltip when switching between multiple triggers with different payloads.

Accessibility

Don't rely on the tooltip as the only label

A tooltip only appears on hover or focus, so it can't be the sole accessible name for an icon-only control. Give the trigger its own text (a visually hidden span or aria-label) and use the tooltip for the same or supplementary hint.

<TooltipTrigger render={<Button variant="outline" size="icon" />}>
  <PlusIcon />
  <span className="sr-only">Add to library</span>
</TooltipTrigger>
<TooltipContent>Add to library</TooltipContent>

API Reference

The Tooltip component is built on top of Base UI's Tooltip. All Base UI props are supported. The documentation below only covers custom props and modified defaults specific to our implementation.

For the complete Base UI API, see the Base UI Tooltip documentation.

Utilities

createTooltipHandle

Creates a handle that connects a tooltip to one or more external TooltipTrigger components. Useful when the triggers need to live outside the Tooltip, for example when each row in a list has its own trigger but they all share one tooltip.

import { createTooltipHandle } from "@/registry/default/tooltip/tooltip";
 
const handle = createTooltipHandle();

Passing data from the trigger to the tooltip

The handle accepts an optional <Payload> generic that types a value each trigger can pass along. The tooltip reads it through a render-prop child, so you can render different content per trigger without duplicating the tooltip markup.

type User = { id: string; name: string };
 
const handle = createTooltipHandle<User>();
 
// Multiple triggers, each with its own payload:
users.map((user) => (
  <TooltipTrigger key={user.id} handle={handle} payload={user}>
    {user.name}
  </TooltipTrigger>
));
 
// One shared tooltip that renders based on the active trigger:
<Tooltip handle={handle}>
  <TooltipContent>{({ payload: user }) => <p>{user?.name}</p>}</TooltipContent>
</Tooltip>;

Without the <User> generic, payload inside the render prop resolves to unknown.

Props

TooltipContent

Composed component for common tooltip layouts. Combines Tooltip.Portal, Tooltip.Positioner, and Tooltip.Popup. Optionally renders Tooltip.Arrow. Props are forwarded to the Positioner and Popup components.

Modified Defaults

Our implementation changes the following Base UI prop defaults:

• TooltipContent: sideOffset defaults to 8 (Base UI defaults to 0)
• TooltipContent: collisionPadding defaults to 10 (Base UI defaults to 5)
• TooltipProvider: delay defaults to 200 (Base UI falls back to 600)