Tooltip

A lightweight tooltip component for displaying contextual information on hover or focus. Built on Radix UI.

Overview

The Tooltip component provides contextual information when users hover over or focus on an element. It's built on Radix UI's Tooltip primitive with design system tokens for consistent styling.

Installation

Install the component via the CLI in one command.

npx @work-rjkashyap/unified-ui add tooltip

pnpm dlx @work-rjkashyap/unified-ui add tooltip

npx @work-rjkashyap/unified-ui add tooltip

bunx @work-rjkashyap/unified-ui add tooltip

If you haven't initialized your project yet, run npx @work-rjkashyap/unified-ui init first. See the CLI docs for details.

Or install the full package

Use this approach if you prefer to install the entire design system as a dependency instead of copying individual components.

npm install @work-rjkashyap/unified-ui

pnpm add @work-rjkashyap/unified-ui

yarn add @work-rjkashyap/unified-ui

bun add @work-rjkashyap/unified-ui

Anatomy

import {
	Tooltip,
	TooltipProvider,
} from "@work-rjkashyap/unified-ui";

Setup

Wrap your application (or a section of it) with TooltipProvider to enable tooltips. This configures shared delay and skip behavior for all tooltips within its scope.

import { TooltipProvider } from "@work-rjkashyap/unified-ui";

export default function RootLayout({ children }) {
	return <TooltipProvider>{children}</TooltipProvider>;
}

Examples

Basic Usage

The trigger element must be a single React element that can accept a ref. If you're wrapping a custom component, make sure it forwards refs.

Placement

<Tooltip content="Top tooltip" side="top">
<Button variant="secondary">Top</Button>
</Tooltip>

<Tooltip content="Right tooltip" side="right">
<Button variant="secondary">Right</Button>
</Tooltip>

<Tooltip content="Bottom tooltip" side="bottom">
<Button variant="secondary">Bottom</Button>
</Tooltip>

<Tooltip content="Left tooltip" side="left">
<Button variant="secondary">Left</Button>
</Tooltip>

<Tooltip content="Top tooltip" side="top"><Button variant="secondary">Top</Button></Tooltip><Tooltip content="Right tooltip" side="right"><Button variant="secondary">Right</Button></Tooltip><Tooltip content="Bottom tooltip" side="bottom"><Button variant="secondary">Bottom</Button></Tooltip><Tooltip content="Left tooltip" side="left"><Button variant="secondary">Left</Button></Tooltip>

Alignment

<Tooltip content="Start aligned" side="bottom" align="start">
<Button variant="secondary">Start</Button>
</Tooltip>

<Tooltip content="Center aligned" side="bottom" align="center">
<Button variant="secondary">Center</Button>
</Tooltip>

<Tooltip content="End aligned" side="bottom" align="end">
<Button variant="secondary">End</Button>
</Tooltip>

<Tooltip content="Start aligned" side="bottom" align="start"><Button variant="secondary">Start</Button></Tooltip><Tooltip content="Center aligned" side="bottom" align="center"><Button variant="secondary">Center</Button></Tooltip><Tooltip content="End aligned" side="bottom" align="end"><Button variant="secondary">End</Button></Tooltip>

With Icon-Only Buttons

<Tooltip content="Settings">
<Button variant="ghost" iconOnly aria-label="Settings">
  <Settings className="size-4" />
</Button>
</Tooltip>

<Tooltip content="Delete">
<Button variant="ghost" iconOnly aria-label="Delete">
	<Trash className="size-4" />
</Button>
</Tooltip>

<Tooltip content="Copy to clipboard">
<Button variant="ghost" iconOnly aria-label="Copy">
	<Copy className="size-4" />
</Button>
</Tooltip>

<Tooltip content="Download">
<Button variant="ghost" iconOnly aria-label="Download">
  <Download className="size-4" />
</Button>
</Tooltip>

<Tooltip content="Settings"><Button variant="ghost" iconOnly aria-label="Settings">  <Settings className="size-4" /></Button></Tooltip><Tooltip content="Delete"><Button variant="ghost" iconOnly aria-label="Delete">	<Trash className="size-4" /></Button></Tooltip><Tooltip content="Copy to clipboard"><Button variant="ghost" iconOnly aria-label="Copy">	<Copy className="size-4" /></Button></Tooltip><Tooltip content="Download"><Button variant="ghost" iconOnly aria-label="Download">  <Download className="size-4" /></Button></Tooltip>

<div className="flex items-center gap-1 p-1 border border-border rounded-md">
<Tooltip content="Bold (Ctrl+B)">
  <Button variant="ghost" size="sm" iconOnly aria-label="Bold">
    <BoldIcon className="size-4" />
  </Button>
</Tooltip>
<Tooltip content="Italic (Ctrl+I)">
  <Button variant="ghost" size="sm" iconOnly aria-label="Italic">
    <ItalicIcon className="size-4" />
  </Button>
</Tooltip>
<Tooltip content="Underline (Ctrl+U)">
  <Button variant="ghost" size="sm" iconOnly aria-label="Underline">
    <UnderlineIcon className="size-4" />
  </Button>
</Tooltip>
</div>

<div className="flex items-center gap-1 p-1 border border-border rounded-md"><Tooltip content="Bold (Ctrl+B)">  <Button variant="ghost" size="sm" iconOnly aria-label="Bold">    <BoldIcon className="size-4" />  </Button></Tooltip><Tooltip content="Italic (Ctrl+I)">  <Button variant="ghost" size="sm" iconOnly aria-label="Italic">    <ItalicIcon className="size-4" />  </Button></Tooltip><Tooltip content="Underline (Ctrl+U)">  <Button variant="ghost" size="sm" iconOnly aria-label="Underline">    <UnderlineIcon className="size-4" />  </Button></Tooltip></div>

Arrow

By default, tooltips show a small arrow pointing toward the trigger. Set arrow={false} to hide it.

{
	/* With arrow (default) */
}
<Tooltip content="With arrow" arrow>
	<Button>Hover me</Button>
</Tooltip>;

{
	/* Without arrow */
}
<Tooltip content="No arrow" arrow={false}>
	<Button>Hover me</Button>
</Tooltip>;

Delay

Configure the open delay to control how quickly the tooltip appears. The TooltipProvider controls the shared delay for all tooltips in its scope.

{
	/* Fast — 200ms delay */
}
<TooltipProvider delayDuration={200}>
	<Tooltip content="Quick tooltip">
		<Button>Fast</Button>
	</Tooltip>
</TooltipProvider>;

{
	/* Slow — 700ms delay */
}
<TooltipProvider delayDuration={700}>
	<Tooltip content="Slow tooltip">
		<Button>Slow</Button>
	</Tooltip>
</TooltipProvider>;

You can also override the delay per tooltip:

<Tooltip content="Custom delay" delayDuration={0}>
	<Button>Instant</Button>
</Tooltip>

Rich Content

The content prop accepts any ReactNode, so you can render rich tooltip content.

<Tooltip
	content={
		<div className="flex flex-col gap-1">
			<p className="font-semibold text-xs">Keyboard Shortcut</p>
			<p className="text-xs text-muted-foreground">
				Press{" "}
				<kbd className="px-1 py-0.5 bg-muted rounded text-[10px]">
					Ctrl+S
				</kbd>{" "}
				to save
			</p>
		</div>
	}
>
	<Button>Save</Button>
</Tooltip>

Max Width

Tooltips have a default max width of 220px to keep content readable. Override with maxWidth.

<Tooltip
	content="This is a very long tooltip message that would normally wrap at the default max width."
	maxWidth={300}
>
	<Button>Wide tooltip</Button>
</Tooltip>

Props

Prop	Type	Default	Description
`content`	`ReactNode`	required	The tooltip content. Can be a string or React node.
`side`	`"top" \| "right" \| "bottom" \| "left"`	`"top"`	Which side the tooltip appears on.
`align`	`"start" \| "center" \| "end"`	`"center"`	Alignment along the side axis.
`arrow`	`boolean`	`true`	Whether to show the arrow indicator.
`sideOffset`	`number`	`4`	Distance in px from the trigger.
`maxWidth`	`number`	`220`	Maximum width of the tooltip in px.
`delayDuration`	`number`	—	Override the provider's delay for this tooltip.
`children`	`ReactElement`	required	The trigger element (must accept a ref).

TooltipProvider

Prop	Type	Default	Description
`delayDuration`	`number`	`400`	Open delay in ms for all tooltips in scope.
`skipDelayDuration`	`number`	`300`	Time in ms before the delay resets after leaving a tooltip.
`disableHoverableContent`	`boolean`	`false`	Prevent tooltip from staying open when hovering over its content.

Accessibility

Built on @radix-ui/react-tooltip which provides full keyboard and screen reader support out of the box.

Keyboard accessible — Tooltips appear when the trigger receives keyboard focus and hide on blur.
Escape to dismiss — Pressing Escape closes the tooltip immediately.
ARIA attributes — The tooltip is linked to its trigger via aria-describedby (managed by Radix).
Screen reader support — The tooltip content is announced when the trigger is focused.
No focus steal — Tooltips don't trap focus. They supplement existing content without blocking interaction.
Hover intent — Configurable delay prevents tooltips from flickering during normal mouse movement.
Skip delay — After viewing one tooltip, subsequent tooltips open faster (controlled by skipDelayDuration).
The tooltip uses z-tooltip for proper layering above page content.
Animations are CSS-based (fade + scale) and respect prefers-reduced-motion.

Design Tokens

Token	Usage
`--foreground`	Tooltip text color
`--popover`	Tooltip background
`--radius-md`	Tooltip border radius
`--z-tooltip`	Z-index for tooltip layer
`--shadow-sm`	Tooltip elevation shadow
`--duration-fast`	Animation timing for enter/exit

On this page