Tooltip

Installation

npx shadcn@latest add @cubby-ui/tooltip

Usage


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


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

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.

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.

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();

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.

Prop

Type

Default

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)

Preview