Tooltip

A popup that displays information related to an element when it receives keyboard focus or hover.

<Tooltip>
  <TooltipTrigger render={<Button variant="outline" />}>
    Hover
  </TooltipTrigger>
  <TooltipContent>
    <p>Add to library</p>
  </TooltipContent>
</Tooltip>

Installation

pnpm dlx cubix@latest add tooltip

Add the Provider

Place TooltipProvider near the root of your app so tooltips share delay and portal behavior.

app/layout.tsx

import { TooltipProvider } from "@/components/cubix/tooltip"

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <TooltipProvider>{children}</TooltipProvider>
      </body>
    </html>
  )
}

Usage

Import

import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@/components/cubix/tooltip"

Example

<Tooltip>
  <TooltipTrigger render={<Button variant="outline" />}>
    Hover
  </TooltipTrigger>
  <TooltipContent>
    <p>Add to library</p>
  </TooltipContent>
</Tooltip>

Composition

Use the following composition to build a Tooltip:

Tooltip
├── TooltipTrigger
└── TooltipContent

Side

Use the side prop to change the position of the tooltip.

<div className="flex flex-wrap gap-2">
  {(["left", "top", "bottom", "right"] as const).map((side) => (
    <Tooltip key={side}>
      <TooltipTrigger
        render={<Button variant="outline" className="w-fit capitalize" />}
      >
        {side}
      </TooltipTrigger>
      <TooltipContent side={side}>
        <p>Add to library</p>
      </TooltipContent>
    </Tooltip>
  ))}
</div>

With Keyboard Shortcut

<Tooltip>
  <TooltipTrigger
    render={<Button variant="outline" size="icon-sm" aria-label="Save" />}
  >
    <SaveIcon />
  </TooltipTrigger>
  <TooltipContent>
    Save Changes <Kbd>S</Kbd>
  </TooltipContent>
</Tooltip>

Disabled Button

Show a tooltip on a disabled button by wrapping it with a span.

<Tooltip>
  <TooltipTrigger render={<span className="inline-block w-fit" />}>
    <Button variant="outline" disabled>
      Disabled
    </Button>
  </TooltipTrigger>
  <TooltipContent>
    <p>This feature is currently unavailable</p>
  </TooltipContent>
</Tooltip>

RTL

Prefer logical sides like inline-start and inline-end when mirroring layout with dir="rtl".

<div dir="rtl" className="flex flex-wrap gap-2">
  {(["top", "bottom", "inline-start", "inline-end"] as const).map((side) => (
    <Tooltip key={side}>
      <TooltipTrigger render={<Button variant="outline" />}>
        {side}
      </TooltipTrigger>
      <TooltipContent side={side}>
        <p>Add to library</p>
      </TooltipContent>
    </Tooltip>
  ))}
</div>

Delay

Wrap tooltips in TooltipProvider to share a custom open delay across a tree.

<TooltipProvider delay={700}>
  <Tooltip>
    <TooltipTrigger render={<Button variant="outline" />}>
      Slow open
    </TooltipTrigger>
    <TooltipContent>Opens after 700ms</TooltipContent>
  </Tooltip>
</TooltipProvider>

API Reference

See also the Base UI Tooltip documentation for primitive props.

TooltipProvider

Prop	Type	Default	Description
delay	number	0	Default delay in milliseconds before any tooltip in the tree opens.
children	React.ReactNode	-	Tooltip trees that share this delay setting.

Tooltip

Prop	Type	Default	Description
open	boolean	-	Controlled open state. Omit to use uncontrolled mode.
defaultOpen	boolean	false	Initial open state when uncontrolled.
onOpenChange	(open: boolean) => void	-	Called when the open state changes.
delay	number	-	Delay in ms before showing. Overrides TooltipProvider when set.
children	React.ReactNode	-	The trigger and content elements.

TooltipTrigger

Prop	Type	Default	Description
render	React.ReactElement	-	Render the trigger as another element (for example a Button).
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).

TooltipContent

Prop	Type	Default	Description
side	"top" \| "right" \| "bottom" \| "left" \| "inline-start" \| "inline-end"	"top"	Preferred side of the trigger to render the tooltip on.
sideOffset	number	4	Distance in pixels between the trigger and the tooltip.
align	"start" \| "center" \| "end"	"center"	Alignment of the tooltip relative to the trigger.
alignOffset	number	0	Offset in pixels along the alignment axis.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).