Get Started
Components
- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
AI Elements
Libraries
Utilities
"use client";
import * as React from "react";
import { createPortal } from "react-dom";
import { parseMotion, useReducedMotion } from "@/lib/motion";
import { cn } from "@/lib/utils";
type TooltipSide = "top" | "right" | "bottom" | "left";
type TooltipAlign = "start" | "center" | "end";
interface TooltipProviderContextValue {
delayDuration: number;
}
const TooltipProviderContext = React.createContext<TooltipProviderContextValue>(
{ delayDuration: 0 }
);
interface TooltipContextValue {
contentId: string;
contentRef: React.RefObject<HTMLDivElement | null>;
onContentEnter: () => void;
onContentLeave: () => void;
onTriggerBlur: () => void;
onTriggerEnter: () => void;
onTriggerFocus: () => void;
onTriggerLeave: () => void;
open: boolean;
setOpen: (open: boolean) => void;
triggerRef: React.RefObject<HTMLElement | null>;
}
const TooltipContext = React.createContext<TooltipContextValue | null>(null);
function useTooltipContext(component: string): TooltipContextValue {
const ctx = React.useContext(TooltipContext);
if (!ctx) {
throw new Error(`${component} must be used within Tooltip`);
}
return ctx;
}
function computeTooltipPosition(
trigger: HTMLElement,
content: HTMLElement,
side: TooltipSide,
align: TooltipAlign,
sideOffset: number,
avoidCollisions: boolean
): { x: number; y: number; side: TooltipSide } {
const t = trigger.getBoundingClientRect();
const c = content.getBoundingClientRect();
const vw = window.innerWidth;
const vh = window.innerHeight;
const place = (s: TooltipSide): { x: number; y: number } => {
let x = 0;
let y = 0;
if (s === "top") {
x = t.left + (t.width - c.width) / 2;
y = t.top - c.height - sideOffset;
} else if (s === "bottom") {
x = t.left + (t.width - c.width) / 2;
y = t.bottom + sideOffset;
} else if (s === "left") {
x = t.left - c.width - sideOffset;
y = t.top + (t.height - c.height) / 2;
} else {
x = t.right + sideOffset;
y = t.top + (t.height - c.height) / 2;
}
if (s === "top" || s === "bottom") {
if (align === "start") {
x = t.left;
} else if (align === "end") {
x = t.right - c.width;
}
} else if (align === "start") {
y = t.top;
} else if (align === "end") {
y = t.bottom - c.height;
}
return { x, y };
};
let resolvedSide = side;
const placed = place(resolvedSide);
let x = placed.x;
let y = placed.y;
if (avoidCollisions) {
const pad = 8;
const over = {
bottom: y + c.height > vh - pad,
left: x < pad,
right: x + c.width > vw - pad,
top: y < pad,
};
const flipMap: Record<TooltipSide, TooltipSide> = {
bottom: "top",
left: "right",
right: "left",
top: "bottom",
};
if (over[resolvedSide]) {
const flipped = flipMap[resolvedSide];
const fp = place(flipped);
const flipOver =
fp.y < pad ||
fp.y + c.height > vh - pad ||
fp.x < pad ||
fp.x + c.width > vw - pad;
if (!flipOver) {
resolvedSide = flipped;
x = fp.x;
y = fp.y;
}
}
if (x < pad) {
x = pad;
}
if (x + c.width > vw - pad) {
x = vw - c.width - pad;
}
if (y < pad) {
y = pad;
}
if (y + c.height > vh - pad) {
y = vh - c.height - pad;
}
}
return { side: resolvedSide, x, y };
}
interface TooltipProviderProps {
children?: React.ReactNode;
delayDuration?: number;
}
function TooltipProvider({
children,
delayDuration = 0,
}: TooltipProviderProps) {
const value = React.useMemo(() => ({ delayDuration }), [delayDuration]);
return (
<TooltipProviderContext.Provider value={value}>
{children}
</TooltipProviderContext.Provider>
);
}
interface TooltipProps {
children?: React.ReactNode;
defaultOpen?: boolean;
onOpenChange?: (open: boolean) => void;
open?: boolean;
}
function Tooltip({
children,
defaultOpen = false,
onOpenChange,
open: openProp,
}: TooltipProps) {
const provider = React.useContext(TooltipProviderContext);
const isControlled = openProp !== undefined;
const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen);
const open = isControlled ? openProp : uncontrolledOpen;
const contentId = React.useId();
const triggerRef = React.useRef<HTMLButtonElement | null>(null);
const contentRef = React.useRef<HTMLDivElement | null>(null);
const openTimer = React.useRef<ReturnType<typeof setTimeout> | null>(null);
const closeTimer = React.useRef<ReturnType<typeof setTimeout> | null>(null);
const clearTimers = React.useCallback(() => {
if (openTimer.current !== null) {
clearTimeout(openTimer.current);
openTimer.current = null;
}
if (closeTimer.current !== null) {
clearTimeout(closeTimer.current);
closeTimer.current = null;
}
}, []);
const setOpen = React.useCallback(
(next: boolean) => {
if (!isControlled) {
setUncontrolledOpen(next);
}
onOpenChange?.(next);
},
[isControlled, onOpenChange]
);
const onTriggerEnter = React.useCallback(() => {
clearTimers();
if (provider.delayDuration > 0) {
openTimer.current = setTimeout(
() => setOpen(true),
provider.delayDuration
);
} else {
setOpen(true);
}
}, [clearTimers, provider.delayDuration, setOpen]);
const onTriggerLeave = React.useCallback(() => {
clearTimers();
closeTimer.current = setTimeout(() => setOpen(false), 80);
}, [clearTimers, setOpen]);
const onContentEnter = React.useCallback(() => {
clearTimers();
}, [clearTimers]);
const onContentLeave = React.useCallback(() => {
clearTimers();
closeTimer.current = setTimeout(() => setOpen(false), 80);
}, [clearTimers, setOpen]);
const onTriggerFocus = React.useCallback(() => {
clearTimers();
setOpen(true);
}, [clearTimers, setOpen]);
const onTriggerBlur = React.useCallback(() => {
clearTimers();
closeTimer.current = setTimeout(() => setOpen(false), 0);
}, [clearTimers, setOpen]);
React.useEffect(
() => () => {
clearTimers();
},
[clearTimers]
);
React.useEffect(() => {
if (!open) {
return;
}
const onKey = (event: KeyboardEvent) => {
if (event.key === "Escape") {
clearTimers();
setOpen(false);
}
};
document.addEventListener("keydown", onKey);
return () => document.removeEventListener("keydown", onKey);
}, [open, clearTimers, setOpen]);
const value = React.useMemo<TooltipContextValue>(
() => ({
contentId,
contentRef,
onContentEnter,
onContentLeave,
onTriggerBlur,
onTriggerEnter,
onTriggerFocus,
onTriggerLeave,
open,
setOpen,
triggerRef,
}),
[
contentId,
onContentEnter,
onContentLeave,
onTriggerBlur,
onTriggerEnter,
onTriggerFocus,
onTriggerLeave,
open,
setOpen,
]
);
return (
<TooltipContext.Provider value={value}>{children}</TooltipContext.Provider>
);
}
type TooltipTriggerProps = Omit<React.ComponentProps<"button">, "ref"> & {
as?: React.ElementType;
asChild?: boolean;
ref?: React.Ref<HTMLElement>;
} & Record<string, unknown>;
function TooltipTrigger({
as,
asChild = false,
children,
onBlur,
onFocus,
onPointerEnter,
onPointerLeave,
ref,
...props
}: TooltipTriggerProps) {
const ctx = useTooltipContext("TooltipTrigger");
const setRef = React.useCallback(
(node: HTMLElement | null) => {
ctx.triggerRef.current = node;
if (typeof ref === "function") {
ref(node);
} else if (ref) {
(ref as React.MutableRefObject<HTMLElement | null>).current = node;
}
},
[ctx.triggerRef, ref]
);
const handlers: Record<string, unknown> = {
"aria-describedby": ctx.open ? ctx.contentId : undefined,
"data-state": ctx.open ? "open" : "closed",
onBlur: (event: React.FocusEvent<HTMLElement>) => {
(onBlur as ((e: React.FocusEvent<HTMLElement>) => void) | undefined)?.(
event
);
ctx.onTriggerBlur();
},
onFocus: (event: React.FocusEvent<HTMLElement>) => {
(onFocus as ((e: React.FocusEvent<HTMLElement>) => void) | undefined)?.(
event
);
ctx.onTriggerFocus();
},
onPointerEnter: (event: React.PointerEvent<HTMLElement>) => {
(
onPointerEnter as
| ((e: React.PointerEvent<HTMLElement>) => void)
| undefined
)?.(event);
ctx.onTriggerEnter();
},
onPointerLeave: (event: React.PointerEvent<HTMLElement>) => {
(
onPointerLeave as
| ((e: React.PointerEvent<HTMLElement>) => void)
| undefined
)?.(event);
ctx.onTriggerLeave();
},
ref: setRef,
};
if (asChild && React.isValidElement(children)) {
return React.cloneElement(
children as React.ReactElement<Record<string, unknown>>,
handlers
);
}
const Comp = (as ?? "button") as React.ElementType;
const isNativeButton = Comp === "button";
return (
<Comp
data-slot="tooltip-trigger"
type={isNativeButton ? ((props.type as string) ?? "button") : undefined}
{...props}
{...handlers}
>
{children}
</Comp>
);
}
interface TooltipContentProps extends Omit<React.ComponentProps<"div">, "ref"> {
align?: TooltipAlign;
avoidCollisions?: boolean;
motion?: string;
ref?: React.Ref<HTMLDivElement>;
side?: TooltipSide;
sideOffset?: number;
}
const defaultTooltipMotion = "120 ease-out";
function TooltipContent({
align = "center",
avoidCollisions = true,
children,
className,
motion,
ref,
side = "bottom",
sideOffset = 10,
style,
...props
}: TooltipContentProps) {
const ctx = useTooltipContext("TooltipContent");
const reduce = useReducedMotion();
const motionValue = motion ?? defaultTooltipMotion;
const internalRef = React.useRef<HTMLDivElement | null>(null);
const [entered, setEntered] = React.useState(false);
const [present, setPresent] = React.useState(false);
const [resolvedSide, setResolvedSide] = React.useState<TooltipSide>(side);
const [pos, setPos] = React.useState<{ x: number; y: number }>({
x: 0,
y: 0,
});
const setRef = React.useCallback(
(node: HTMLDivElement | null) => {
internalRef.current = node;
ctx.contentRef.current = node;
if (typeof ref === "function") {
ref(node);
} else if (ref) {
(ref as React.MutableRefObject<HTMLDivElement | null>).current = node;
}
},
[ctx.contentRef, ref]
);
React.useLayoutEffect(() => {
if (!present) {
return;
}
const trigger = ctx.triggerRef.current;
const content = internalRef.current;
if (!(trigger && content)) {
return;
}
const update = () => {
const t = ctx.triggerRef.current;
const c = internalRef.current;
if (!(t && c)) {
return;
}
const next = computeTooltipPosition(
t,
c,
side,
align,
sideOffset,
avoidCollisions
);
setPos({ x: next.x, y: next.y });
setResolvedSide(next.side);
};
update();
window.addEventListener("scroll", update, true);
window.addEventListener("resize", update);
let observer: ResizeObserver | undefined;
if (typeof ResizeObserver !== "undefined") {
observer = new ResizeObserver(update);
observer.observe(trigger);
observer.observe(content);
}
return () => {
window.removeEventListener("scroll", update, true);
window.removeEventListener("resize", update);
observer?.disconnect();
};
}, [present, side, align, sideOffset, avoidCollisions, ctx.triggerRef]);
const parsedMotion = parseMotion(motionValue);
const exitDuration =
reduce || parsedMotion?.disabled ? 0 : (parsedMotion?.duration ?? 120);
React.useEffect(() => {
if (ctx.open) {
setPresent(true);
let raf1 = 0;
let raf2 = 0;
raf1 = requestAnimationFrame(() => {
raf2 = requestAnimationFrame(() => setEntered(true));
});
return () => {
if (raf1) {
cancelAnimationFrame(raf1);
}
if (raf2) {
cancelAnimationFrame(raf2);
}
};
}
setEntered(false);
const timer = setTimeout(() => setPresent(false), exitDuration);
return () => clearTimeout(timer);
}, [ctx.open, exitDuration]);
if (!present) {
return null;
}
const baseStyle: React.CSSProperties = {
left: pos.x,
opacity: reduce ? 1 : entered ? 1 : 0,
position: "fixed",
top: pos.y,
...style,
};
if (reduce) {
baseStyle.transition = "none";
} else {
const parsed = parseMotion(motionValue);
if (parsed?.disabled) {
baseStyle.transition = "none";
} else if (parsed) {
baseStyle.transition = `opacity ${parsed.duration}ms ${parsed.easing}`;
} else {
baseStyle.transition = "opacity 120ms ease-out, transform 120ms ease-out";
}
}
const arrowSize = 8;
const arrowStyle: React.CSSProperties = {
background: "var(--foreground)",
height: arrowSize,
position: "absolute",
transform: "rotate(45deg)",
width: arrowSize,
};
if (resolvedSide === "top") {
arrowStyle.bottom = -arrowSize / 4;
if (align === "start") {
arrowStyle.left = 12;
} else if (align === "end") {
arrowStyle.right = 12;
} else {
arrowStyle.left = "50%";
arrowStyle.marginLeft = -arrowSize / 2;
}
} else if (resolvedSide === "bottom") {
arrowStyle.top = -arrowSize / 4;
if (align === "start") {
arrowStyle.left = 12;
} else if (align === "end") {
arrowStyle.right = 12;
} else {
arrowStyle.left = "50%";
arrowStyle.marginLeft = -arrowSize / 2;
}
} else if (resolvedSide === "left") {
arrowStyle.right = -arrowSize / 4;
if (align === "start") {
arrowStyle.top = 12;
} else if (align === "end") {
arrowStyle.bottom = 12;
} else {
arrowStyle.top = "50%";
arrowStyle.marginTop = -arrowSize / 2;
}
} else {
arrowStyle.left = -arrowSize / 4;
if (align === "start") {
arrowStyle.top = 12;
} else if (align === "end") {
arrowStyle.bottom = 12;
} else {
arrowStyle.top = "50%";
arrowStyle.marginTop = -arrowSize / 2;
}
}
return createPortal(
<div
className={cn(
"bg-foreground text-background z-50 inline-flex w-fit max-w-xs items-center gap-1.5 overflow-visible rounded-md px-3 py-1.5 text-xs",
className
)}
data-align={align}
data-side={resolvedSide}
data-slot="tooltip-content"
data-state={ctx.open ? "open" : "closed"}
id={ctx.contentId}
onPointerEnter={ctx.onContentEnter}
onPointerLeave={ctx.onContentLeave}
ref={setRef}
role="tooltip"
style={baseStyle}
{...props}
>
<span aria-hidden="true" style={arrowStyle} />
{children}
</div>,
document.body
);
}
export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger };Tooltip shows a small label on hover or focus. It supports side / align / sideOffset via floating-ui, and requires wrapping the app in TooltipProvider only if you want a shared delay.
Installation
$ bunx --bun frakment add tooltip$ npx frakment add tooltip$ pnpm dlx frakment add tooltip$ yarn dlx frakment add tooltip
Install the following dependency:
$ bun add @floating-ui/react-dom$ npm install @floating-ui/react-dom$ pnpm add @floating-ui/react-dom$ yarn add @floating-ui/react-dom
Copy and paste the following code into your project.
"use client";
import * as React from "react";
import { createPortal } from "react-dom";
import { parseMotion, useReducedMotion } from "@/lib/motion";
import { cn } from "@/lib/utils";
type TooltipSide = "top" | "right" | "bottom" | "left";
type TooltipAlign = "start" | "center" | "end";
interface TooltipProviderContextValue {
delayDuration: number;
}
const TooltipProviderContext = React.createContext<TooltipProviderContextValue>(
{ delayDuration: 0 }
);
interface TooltipContextValue {
contentId: string;
contentRef: React.RefObject<HTMLDivElement | null>;
onContentEnter: () => void;
onContentLeave: () => void;
onTriggerBlur: () => void;
onTriggerEnter: () => void;
onTriggerFocus: () => void;
onTriggerLeave: () => void;
open: boolean;
setOpen: (open: boolean) => void;
triggerRef: React.RefObject<HTMLElement | null>;
}
const TooltipContext = React.createContext<TooltipContextValue | null>(null);
function useTooltipContext(component: string): TooltipContextValue {
const ctx = React.useContext(TooltipContext);
if (!ctx) {
throw new Error(`${component} must be used within Tooltip`);
}
return ctx;
}
function computeTooltipPosition(
trigger: HTMLElement,
content: HTMLElement,
side: TooltipSide,
align: TooltipAlign,
sideOffset: number,
avoidCollisions: boolean
): { x: number; y: number; side: TooltipSide } {
const t = trigger.getBoundingClientRect();
const c = content.getBoundingClientRect();
const vw = window.innerWidth;
const vh = window.innerHeight;
const place = (s: TooltipSide): { x: number; y: number } => {
let x = 0;
let y = 0;
if (s === "top") {
x = t.left + (t.width - c.width) / 2;
y = t.top - c.height - sideOffset;
} else if (s === "bottom") {
x = t.left + (t.width - c.width) / 2;
y = t.bottom + sideOffset;
} else if (s === "left") {
x = t.left - c.width - sideOffset;
y = t.top + (t.height - c.height) / 2;
} else {
x = t.right + sideOffset;
y = t.top + (t.height - c.height) / 2;
}
if (s === "top" || s === "bottom") {
if (align === "start") {
x = t.left;
} else if (align === "end") {
x = t.right - c.width;
}
} else if (align === "start") {
y = t.top;
} else if (align === "end") {
y = t.bottom - c.height;
}
return { x, y };
};
let resolvedSide = side;
const placed = place(resolvedSide);
let x = placed.x;
let y = placed.y;
if (avoidCollisions) {
const pad = 8;
const over = {
bottom: y + c.height > vh - pad,
left: x < pad,
right: x + c.width > vw - pad,
top: y < pad,
};
const flipMap: Record<TooltipSide, TooltipSide> = {
bottom: "top",
left: "right",
right: "left",
top: "bottom",
};
if (over[resolvedSide]) {
const flipped = flipMap[resolvedSide];
const fp = place(flipped);
const flipOver =
fp.y < pad ||
fp.y + c.height > vh - pad ||
fp.x < pad ||
fp.x + c.width > vw - pad;
if (!flipOver) {
resolvedSide = flipped;
x = fp.x;
y = fp.y;
}
}
if (x < pad) {
x = pad;
}
if (x + c.width > vw - pad) {
x = vw - c.width - pad;
}
if (y < pad) {
y = pad;
}
if (y + c.height > vh - pad) {
y = vh - c.height - pad;
}
}
return { side: resolvedSide, x, y };
}
interface TooltipProviderProps {
children?: React.ReactNode;
delayDuration?: number;
}
function TooltipProvider({
children,
delayDuration = 0,
}: TooltipProviderProps) {
const value = React.useMemo(() => ({ delayDuration }), [delayDuration]);
return (
<TooltipProviderContext.Provider value={value}>
{children}
</TooltipProviderContext.Provider>
);
}
interface TooltipProps {
children?: React.ReactNode;
defaultOpen?: boolean;
onOpenChange?: (open: boolean) => void;
open?: boolean;
}
function Tooltip({
children,
defaultOpen = false,
onOpenChange,
open: openProp,
}: TooltipProps) {
const provider = React.useContext(TooltipProviderContext);
const isControlled = openProp !== undefined;
const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen);
const open = isControlled ? openProp : uncontrolledOpen;
const contentId = React.useId();
const triggerRef = React.useRef<HTMLButtonElement | null>(null);
const contentRef = React.useRef<HTMLDivElement | null>(null);
const openTimer = React.useRef<ReturnType<typeof setTimeout> | null>(null);
const closeTimer = React.useRef<ReturnType<typeof setTimeout> | null>(null);
const clearTimers = React.useCallback(() => {
if (openTimer.current !== null) {
clearTimeout(openTimer.current);
openTimer.current = null;
}
if (closeTimer.current !== null) {
clearTimeout(closeTimer.current);
closeTimer.current = null;
}
}, []);
const setOpen = React.useCallback(
(next: boolean) => {
if (!isControlled) {
setUncontrolledOpen(next);
}
onOpenChange?.(next);
},
[isControlled, onOpenChange]
);
const onTriggerEnter = React.useCallback(() => {
clearTimers();
if (provider.delayDuration > 0) {
openTimer.current = setTimeout(
() => setOpen(true),
provider.delayDuration
);
} else {
setOpen(true);
}
}, [clearTimers, provider.delayDuration, setOpen]);
const onTriggerLeave = React.useCallback(() => {
clearTimers();
closeTimer.current = setTimeout(() => setOpen(false), 80);
}, [clearTimers, setOpen]);
const onContentEnter = React.useCallback(() => {
clearTimers();
}, [clearTimers]);
const onContentLeave = React.useCallback(() => {
clearTimers();
closeTimer.current = setTimeout(() => setOpen(false), 80);
}, [clearTimers, setOpen]);
const onTriggerFocus = React.useCallback(() => {
clearTimers();
setOpen(true);
}, [clearTimers, setOpen]);
const onTriggerBlur = React.useCallback(() => {
clearTimers();
closeTimer.current = setTimeout(() => setOpen(false), 0);
}, [clearTimers, setOpen]);
React.useEffect(
() => () => {
clearTimers();
},
[clearTimers]
);
React.useEffect(() => {
if (!open) {
return;
}
const onKey = (event: KeyboardEvent) => {
if (event.key === "Escape") {
clearTimers();
setOpen(false);
}
};
document.addEventListener("keydown", onKey);
return () => document.removeEventListener("keydown", onKey);
}, [open, clearTimers, setOpen]);
const value = React.useMemo<TooltipContextValue>(
() => ({
contentId,
contentRef,
onContentEnter,
onContentLeave,
onTriggerBlur,
onTriggerEnter,
onTriggerFocus,
onTriggerLeave,
open,
setOpen,
triggerRef,
}),
[
contentId,
onContentEnter,
onContentLeave,
onTriggerBlur,
onTriggerEnter,
onTriggerFocus,
onTriggerLeave,
open,
setOpen,
]
);
return (
<TooltipContext.Provider value={value}>{children}</TooltipContext.Provider>
);
}
type TooltipTriggerProps = Omit<React.ComponentProps<"button">, "ref"> & {
as?: React.ElementType;
asChild?: boolean;
ref?: React.Ref<HTMLElement>;
} & Record<string, unknown>;
function TooltipTrigger({
as,
asChild = false,
children,
onBlur,
onFocus,
onPointerEnter,
onPointerLeave,
ref,
...props
}: TooltipTriggerProps) {
const ctx = useTooltipContext("TooltipTrigger");
const setRef = React.useCallback(
(node: HTMLElement | null) => {
ctx.triggerRef.current = node;
if (typeof ref === "function") {
ref(node);
} else if (ref) {
(ref as React.MutableRefObject<HTMLElement | null>).current = node;
}
},
[ctx.triggerRef, ref]
);
const handlers: Record<string, unknown> = {
"aria-describedby": ctx.open ? ctx.contentId : undefined,
"data-state": ctx.open ? "open" : "closed",
onBlur: (event: React.FocusEvent<HTMLElement>) => {
(onBlur as ((e: React.FocusEvent<HTMLElement>) => void) | undefined)?.(
event
);
ctx.onTriggerBlur();
},
onFocus: (event: React.FocusEvent<HTMLElement>) => {
(onFocus as ((e: React.FocusEvent<HTMLElement>) => void) | undefined)?.(
event
);
ctx.onTriggerFocus();
},
onPointerEnter: (event: React.PointerEvent<HTMLElement>) => {
(
onPointerEnter as
| ((e: React.PointerEvent<HTMLElement>) => void)
| undefined
)?.(event);
ctx.onTriggerEnter();
},
onPointerLeave: (event: React.PointerEvent<HTMLElement>) => {
(
onPointerLeave as
| ((e: React.PointerEvent<HTMLElement>) => void)
| undefined
)?.(event);
ctx.onTriggerLeave();
},
ref: setRef,
};
if (asChild && React.isValidElement(children)) {
return React.cloneElement(
children as React.ReactElement<Record<string, unknown>>,
handlers
);
}
const Comp = (as ?? "button") as React.ElementType;
const isNativeButton = Comp === "button";
return (
<Comp
data-slot="tooltip-trigger"
type={isNativeButton ? ((props.type as string) ?? "button") : undefined}
{...props}
{...handlers}
>
{children}
</Comp>
);
}
interface TooltipContentProps extends Omit<React.ComponentProps<"div">, "ref"> {
align?: TooltipAlign;
avoidCollisions?: boolean;
motion?: string;
ref?: React.Ref<HTMLDivElement>;
side?: TooltipSide;
sideOffset?: number;
}
const defaultTooltipMotion = "120 ease-out";
function TooltipContent({
align = "center",
avoidCollisions = true,
children,
className,
motion,
ref,
side = "bottom",
sideOffset = 10,
style,
...props
}: TooltipContentProps) {
const ctx = useTooltipContext("TooltipContent");
const reduce = useReducedMotion();
const motionValue = motion ?? defaultTooltipMotion;
const internalRef = React.useRef<HTMLDivElement | null>(null);
const [entered, setEntered] = React.useState(false);
const [present, setPresent] = React.useState(false);
const [resolvedSide, setResolvedSide] = React.useState<TooltipSide>(side);
const [pos, setPos] = React.useState<{ x: number; y: number }>({
x: 0,
y: 0,
});
const setRef = React.useCallback(
(node: HTMLDivElement | null) => {
internalRef.current = node;
ctx.contentRef.current = node;
if (typeof ref === "function") {
ref(node);
} else if (ref) {
(ref as React.MutableRefObject<HTMLDivElement | null>).current = node;
}
},
[ctx.contentRef, ref]
);
React.useLayoutEffect(() => {
if (!present) {
return;
}
const trigger = ctx.triggerRef.current;
const content = internalRef.current;
if (!(trigger && content)) {
return;
}
const update = () => {
const t = ctx.triggerRef.current;
const c = internalRef.current;
if (!(t && c)) {
return;
}
const next = computeTooltipPosition(
t,
c,
side,
align,
sideOffset,
avoidCollisions
);
setPos({ x: next.x, y: next.y });
setResolvedSide(next.side);
};
update();
window.addEventListener("scroll", update, true);
window.addEventListener("resize", update);
let observer: ResizeObserver | undefined;
if (typeof ResizeObserver !== "undefined") {
observer = new ResizeObserver(update);
observer.observe(trigger);
observer.observe(content);
}
return () => {
window.removeEventListener("scroll", update, true);
window.removeEventListener("resize", update);
observer?.disconnect();
};
}, [present, side, align, sideOffset, avoidCollisions, ctx.triggerRef]);
const parsedMotion = parseMotion(motionValue);
const exitDuration =
reduce || parsedMotion?.disabled ? 0 : (parsedMotion?.duration ?? 120);
React.useEffect(() => {
if (ctx.open) {
setPresent(true);
let raf1 = 0;
let raf2 = 0;
raf1 = requestAnimationFrame(() => {
raf2 = requestAnimationFrame(() => setEntered(true));
});
return () => {
if (raf1) {
cancelAnimationFrame(raf1);
}
if (raf2) {
cancelAnimationFrame(raf2);
}
};
}
setEntered(false);
const timer = setTimeout(() => setPresent(false), exitDuration);
return () => clearTimeout(timer);
}, [ctx.open, exitDuration]);
if (!present) {
return null;
}
const baseStyle: React.CSSProperties = {
left: pos.x,
opacity: reduce ? 1 : entered ? 1 : 0,
position: "fixed",
top: pos.y,
...style,
};
if (reduce) {
baseStyle.transition = "none";
} else {
const parsed = parseMotion(motionValue);
if (parsed?.disabled) {
baseStyle.transition = "none";
} else if (parsed) {
baseStyle.transition = `opacity ${parsed.duration}ms ${parsed.easing}`;
} else {
baseStyle.transition = "opacity 120ms ease-out, transform 120ms ease-out";
}
}
const arrowSize = 8;
const arrowStyle: React.CSSProperties = {
background: "var(--foreground)",
height: arrowSize,
position: "absolute",
transform: "rotate(45deg)",
width: arrowSize,
};
if (resolvedSide === "top") {
arrowStyle.bottom = -arrowSize / 4;
if (align === "start") {
arrowStyle.left = 12;
} else if (align === "end") {
arrowStyle.right = 12;
} else {
arrowStyle.left = "50%";
arrowStyle.marginLeft = -arrowSize / 2;
}
} else if (resolvedSide === "bottom") {
arrowStyle.top = -arrowSize / 4;
if (align === "start") {
arrowStyle.left = 12;
} else if (align === "end") {
arrowStyle.right = 12;
} else {
arrowStyle.left = "50%";
arrowStyle.marginLeft = -arrowSize / 2;
}
} else if (resolvedSide === "left") {
arrowStyle.right = -arrowSize / 4;
if (align === "start") {
arrowStyle.top = 12;
} else if (align === "end") {
arrowStyle.bottom = 12;
} else {
arrowStyle.top = "50%";
arrowStyle.marginTop = -arrowSize / 2;
}
} else {
arrowStyle.left = -arrowSize / 4;
if (align === "start") {
arrowStyle.top = 12;
} else if (align === "end") {
arrowStyle.bottom = 12;
} else {
arrowStyle.top = "50%";
arrowStyle.marginTop = -arrowSize / 2;
}
}
return createPortal(
<div
className={cn(
"bg-foreground text-background z-50 inline-flex w-fit max-w-xs items-center gap-1.5 overflow-visible rounded-md px-3 py-1.5 text-xs",
className
)}
data-align={align}
data-side={resolvedSide}
data-slot="tooltip-content"
data-state={ctx.open ? "open" : "closed"}
id={ctx.contentId}
onPointerEnter={ctx.onContentEnter}
onPointerLeave={ctx.onContentLeave}
ref={setRef}
role="tooltip"
style={baseStyle}
{...props}
>
<span aria-hidden="true" style={arrowStyle} />
{children}
</div>,
document.body
);
}
export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger };Update the import paths to match your project setup.
Usage
import {
Tooltip,
TooltipContent,
TooltipTrigger,
} from "@/components/ui/tooltip";<Tooltip>
<TooltipTrigger as={Button} variant="outline">Hover</TooltipTrigger>
<TooltipContent>Add to library</TooltipContent>
</Tooltip>Composition
TooltipProvider (optional)
└── Tooltip
├── TooltipTrigger
└── TooltipContentExamples
Sides
import { Button } from "@/components/ui/button";
import {
Tooltip,
TooltipContent,
TooltipTrigger,
} from "@/components/ui/tooltip";
export function TooltipSides() {
return (
<div className="flex flex-wrap gap-2">
{(["left", "top", "bottom", "right"] as const).map((side) => (
<Tooltip key={side}>
<TooltipTrigger
as={Button}
className="w-fit capitalize"
variant="outline"
>
{side}
</TooltipTrigger>
<TooltipContent side={side}>Add to library</TooltipContent>
</Tooltip>
))}
</div>
);
}Disabled trigger
Wrap a disabled button in a <span> — the trigger needs a hoverable host to receive pointer events.
import { Button } from "@/components/ui/button";
import {
Tooltip,
TooltipContent,
TooltipTrigger,
} from "@/components/ui/tooltip";
export function TooltipDisabled() {
return (
<Tooltip>
<TooltipTrigger as="span" className="inline-block w-fit">
<Button disabled variant="outline">
Disabled
</Button>
</TooltipTrigger>
<TooltipContent>This feature is currently unavailable</TooltipContent>
</Tooltip>
);
}In Context
Icon button hint
import { CopyIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import {
Tooltip,
TooltipContent,
TooltipTrigger,
} from "@/components/ui/tooltip";
export function TooltipIconHint() {
return (
<Tooltip>
<TooltipTrigger aria-label="Copy" as={Button} size="icon" variant="ghost">
<CopyIcon />
</TooltipTrigger>
<TooltipContent>Copy to clipboard</TooltipContent>
</Tooltip>
);
}Anatomy
import { Button } from "@/components/ui/button";
import {
Tooltip,
TooltipContent,
TooltipTrigger,
} from "@/components/ui/tooltip";
export function TooltipAnatomy() {
return (
<Tooltip>
<TooltipTrigger as={Button} variant="outline">
Hover me
</TooltipTrigger>
<TooltipContent>Tooltip content</TooltipContent>
</Tooltip>
);
}- Tooltip — state container for open/closed
- TooltipTrigger — hover/focus target
- TooltipContent — floating panel rendered in a portal
API Reference
TooltipProvider
| Prop | Type | Default | Description |
|---|---|---|---|
delayDuration | number | — | Delay before the tooltip appears (ms). Shared across all tooltips under the provider. |
Tooltip
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | — | Controlled open state. |
defaultOpen | boolean | — | Uncontrolled initial state. |
onOpenChange | (open: boolean) => void | — | Fires when the tooltip opens or closes. |
TooltipTrigger
| Prop | Type | Default | Description |
|---|---|---|---|
as | React.ElementType | — | Render as a different element or component. Accepts tag names or React components. Defaults to button. |
TooltipContent
| Prop | Type | Default | Description |
|---|---|---|---|
side | toprightbottomleft | — | Preferred side relative to the trigger. |
align | startcenterend | — | Alignment along the side axis. |
sideOffset | number | — | Distance from the trigger in pixels. |
avoidCollisions | boolean | — | Flip and shift to stay inside the viewport. |
motion | string | — | CSS transition override for entrance; e.g. 150 ease-out or 200 cubic-bezier(...). Respects prefers-reduced-motion. |
Motion
The tooltip fades in with a default 150ms cubic-bezier(0.16, 1, 0.3, 1) transition. Override with motion:
<TooltipContent motion="200 ease-out">Read more</TooltipContent>| Value | Result |
|---|---|
| omitted | 150ms cubic-bezier default |
"200" | 200ms ease-in-out |
"300 cubic-bezier(...)" | 300ms custom easing |
"off" | instant (no transition) |
When prefers-reduced-motion is set, the transition is disabled. Third-party animation libraries that write inline styles to the tooltip automatically suppress the internal CSS transition.
Keyboard
| Key | Action |
|---|---|
Tab | Focus the trigger, opens the tooltip |
Esc | Close the tooltip |
Data Attributes
| Attribute | Values |
|---|---|
data-slot | tooltip-trigger, tooltip-content |
data-state | open | closed |
data-side | top | right | bottom | left |
data-align | start | center | end |
Accessibility
- The trigger receives
aria-describedbypointing to the tooltip content id when open. - Tooltip content renders
role="tooltip". - Icon-only triggers need
aria-label; the tooltip is supplementary text. - Keyboard:
Tabopens on focus,Esccloses.
Best Practices
- Never put essential text in a tooltip. Use a visible label.
- Keep it short. A phrase, not a sentence.
- Do not stack tooltips. One open at a time.
- Wrap around a real element. Use
as={Button}oras={Link}so the trigger is focusable.
Related Components
- Popover — click-triggered panel
- Hover Card — rich content on hover