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,
  TooltipTrigger,
} from "@/components/ui/cubby-ui/tooltip";

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

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.

Examples

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)