Tooltip
Small labels and previews that appear on hover and focus, from plain names to cards with links inside.
Standard
A short label for icon buttons. Waits before the first one opens, then opens instantly while you scan neighbors.
Installation
$npx shadcn@latest add @stillui/tooltipOr copy the source into your project. It needs the shadcn color tokens and the cn helper.
"use client";
// stillui.dev/components/tooltip
import { AnimatePresence, motion, useReducedMotion } from "motion/react";
import { useEffect, useId, useRef, useState, type ReactNode } from "react";
import { cn } from "@/lib/utils";
const OPEN_DELAY = 500;
// Once one tooltip has opened, neighbors open at once for a short while,
// so scanning a toolbar doesn't mean waiting at every icon.
const WARM_WINDOW = 400;
let lastClosedAt = 0;
type TooltipProps = {
content: ReactNode;
side?: "top" | "bottom";
children: ReactNode;
className?: string;
};
export function Tooltip({ content, side = "top", children, className }: TooltipProps) {
const reduce = useReducedMotion();
const [open, setOpen] = useState(false);
const timer = useRef<number | undefined>(undefined);
const id = useId();
useEffect(() => () => window.clearTimeout(timer.current), []);
const show = () => {
window.clearTimeout(timer.current);
const warm = Date.now() - lastClosedAt < WARM_WINDOW;
timer.current = window.setTimeout(() => setOpen(true), warm ? 0 : OPEN_DELAY);
};
const hide = () => {
window.clearTimeout(timer.current);
setOpen((wasOpen) => {
if (wasOpen) lastClosedAt = Date.now();
return false;
});
};
const offset = side === "top" ? 4 : -4;
return (
<span
className="relative inline-flex"
onPointerEnter={(e) => e.pointerType === "mouse" && show()}
onPointerLeave={hide}
onFocus={() => setOpen(true)}
onBlur={hide}
onKeyDown={(e) => e.key === "Escape" && hide()}
aria-describedby={open ? id : undefined}
>
{children}
<AnimatePresence>
{open ? (
<motion.span
id={id}
role="tooltip"
className={cn(
"pointer-events-none absolute left-1/2 z-50 w-max max-w-60 -translate-x-1/2 rounded-md bg-primary px-2.5 py-1.5",
"text-[13px] leading-snug text-primary-foreground shadow-overlay",
side === "top" ? "bottom-full mb-2" : "top-full mt-2",
className,
)}
initial={{ opacity: 0, y: reduce ? 0 : offset, scale: reduce ? 1 : 0.97 }}
animate={{ opacity: 1, y: 0, scale: 1 }}
exit={{ opacity: 0, transition: { duration: 0.08 } }}
transition={{ duration: 0.14, ease: [0.16, 1, 0.3, 1] }}
style={{ originY: side === "top" ? 1 : 0 }}
>
{content}
</motion.span>
) : null}
</AnimatePresence>
</span>
);
}States
- Resting
- Hidden. Nothing in the layout reserves space for it.
- Hover
- Opens after 500ms, so passing over a toolbar doesn't flash labels.
- Warm
- Within 400ms of one closing, the next opens with no delay.
- Keyboard focus
- Opens at once on focus. Escape closes it. Linked to the trigger with aria-describedby.
- Touch
- Not shown: touch screens have no hover. The trigger keeps its own accessible label.
Notes
Tooltips are for names and shortcuts, never for information someone needs to finish a task. Touch users won’t see them.
Keep the text to a few words. If it needs a sentence, it belongs on the page.
Follow cursor
A tooltip that follows the pointer along a wide target, like a chart or timeline, and reads out what’s under it.
Commits in the last 30 days
Installation
$npx shadcn@latest add @stillui/tooltip-followOr copy the source into your project. It needs the shadcn color tokens and the cn helper.
"use client";
// stillui.dev/components/tooltip#follow
import { AnimatePresence, motion, useMotionValue, useReducedMotion, useSpring } from "motion/react";
import { useState, type PointerEvent, type ReactNode } from "react";
import { cn } from "@/lib/utils";
const FOLLOW = { stiffness: 700, damping: 50, mass: 0.5 } as const;
type TooltipFollowProps = {
/** Gets the pointer’s position across the target, from 0 (left) to 1 (right). */
content: (ratio: number) => ReactNode;
children: ReactNode;
className?: string;
};
/** A tooltip that follows the pointer along a wide target, like a chart or a timeline, and reads out what’s under it. */
export function TooltipFollow({ content, children, className }: TooltipFollowProps) {
const reduce = useReducedMotion();
const [ratio, setRatio] = useState<number | null>(null);
const raw = useMotionValue(0);
const x = useSpring(raw, reduce ? { stiffness: 10000, damping: 1000 } : FOLLOW);
const move = (event: PointerEvent<HTMLDivElement>) => {
const rect = event.currentTarget.getBoundingClientRect();
const next = Math.min(1, Math.max(0, (event.clientX - rect.left) / rect.width));
if (ratio === null) x.jump(event.clientX - rect.left);
raw.set(event.clientX - rect.left);
setRatio(next);
};
return (
<div className={cn("relative", className)} onPointerMove={move} onPointerLeave={() => setRatio(null)}>
{children}
<AnimatePresence>
{ratio !== null ? (
<motion.div
aria-hidden
className="pointer-events-none absolute bottom-full left-0 z-50 mb-2"
style={{ x }}
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0, transition: { duration: 0.08 } }}
transition={{ duration: 0.12 }}
>
<div className="w-max max-w-60 -translate-x-1/2 rounded-md bg-primary px-2.5 py-1.5 text-[13px] leading-snug text-primary-foreground shadow-overlay">
{content(ratio)}
</div>
</motion.div>
) : null}
</AnimatePresence>
</div>
);
}States
- Enter
- Appears right at the pointer without sliding in from elsewhere.
- Moving
- Follows the pointer on a tight spring, so it keeps up without jitter.
- Content
- Your function gets the position from 0 to 1 and returns what to show there.
- Leave
- Fades out quickly when the pointer leaves the target.
- Reduced motion
- Sticks to the pointer exactly, with no spring.
Notes
Mouse only, and hidden from screen readers. Give the chart itself a text summary, as the demo does with its label.
Shortcut
A tooltip that teaches the keyboard shortcut along with the name, so people learn the faster way as they go.
Installation
$npx shadcn@latest add @stillui/tooltip-shortcutOr copy the source into your project. It needs the shadcn color tokens and the cn helper.
"use client";
// stillui.dev/components/tooltip#shortcut
import { AnimatePresence, motion, useReducedMotion } from "motion/react";
import { useEffect, useId, useRef, useState, type ReactNode } from "react";
import { cn } from "@/lib/utils";
const OPEN_DELAY = 500;
const WARM_WINDOW = 400;
let lastClosedAt = 0;
type TooltipShortcutProps = {
label: string;
/** Keys to press, e.g. ["⌘", "B"]. */
keys: string[];
side?: "top" | "bottom";
children: ReactNode;
};
/** A tooltip that teaches the keyboard shortcut along with the name. */
export function TooltipShortcut({ label, keys, side = "top", children }: TooltipShortcutProps) {
const reduce = useReducedMotion();
const [open, setOpen] = useState(false);
const timer = useRef<number | undefined>(undefined);
const id = useId();
useEffect(() => () => window.clearTimeout(timer.current), []);
const show = () => {
window.clearTimeout(timer.current);
const warm = Date.now() - lastClosedAt < WARM_WINDOW;
timer.current = window.setTimeout(() => setOpen(true), warm ? 0 : OPEN_DELAY);
};
const hide = () => {
window.clearTimeout(timer.current);
setOpen((wasOpen) => {
if (wasOpen) lastClosedAt = Date.now();
return false;
});
};
return (
<span
className="relative inline-flex"
onPointerEnter={(e) => e.pointerType === "mouse" && show()}
onPointerLeave={hide}
onFocus={() => setOpen(true)}
onBlur={hide}
onKeyDown={(e) => e.key === "Escape" && hide()}
aria-describedby={open ? id : undefined}
>
{children}
<AnimatePresence>
{open ? (
<motion.span
id={id}
role="tooltip"
className={cn(
"pointer-events-none absolute left-1/2 z-50 flex w-max -translate-x-1/2 items-center gap-2 rounded-md bg-primary py-1 pl-2.5 pr-1 text-[13px] text-primary-foreground shadow-overlay",
side === "top" ? "bottom-full mb-2" : "top-full mt-2",
)}
initial={{ opacity: 0, y: reduce ? 0 : side === "top" ? 4 : -4 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, transition: { duration: 0.08 } }}
transition={{ duration: 0.14, ease: [0.16, 1, 0.3, 1] }}
>
{label}
<span className="flex gap-0.5">
{keys.map((key) => (
<kbd key={key} className="grid h-5 min-w-5 place-items-center rounded bg-primary-foreground/15 px-1 font-sans text-[11px] font-medium">
{key}
</kbd>
))}
</span>
</motion.span>
) : null}
</AnimatePresence>
</span>
);
}States
- Waiting
- Opens after half a second, so passing over a toolbar doesn’t flash tooltips.
- Warm
- Right after one closes, neighbours open instantly while you scan.
- Keys
- Each key sits in its own soft cap beside the label.
- Keyboard focus
- Opens at once on focus; Escape closes it.
- Reduced motion
- Fades without moving.
Notes
Also set aria-keyshortcuts on the button, so screen readers announce the shortcut too.
Hover card
A larger preview, like a profile or link card, that opens on hover and stays open while you move into it.
The new checkout was designed by Amara Okafor and shipped last week.
Installation
$npx shadcn@latest add @stillui/tooltip-cardOr copy the source into your project. It needs the shadcn color tokens and the cn helper.
"use client";
// stillui.dev/components/tooltip#card
import { AnimatePresence, motion, useReducedMotion } from "motion/react";
import { useEffect, useId, useRef, useState, type ReactNode } from "react";
import { cn } from "@/lib/utils";
const OPEN_DELAY = 600;
// A short grace period lets the pointer travel from the trigger into the card.
const CLOSE_DELAY = 150;
type TooltipCardProps = {
/** Rich content: a profile, a link preview, a definition. */
content: ReactNode;
side?: "top" | "bottom";
children: ReactNode;
className?: string;
};
/** A larger preview that opens on hover and stays open while the pointer moves into it, so links inside work. */
export function TooltipCard({ content, side = "bottom", children, className }: TooltipCardProps) {
const reduce = useReducedMotion();
const [open, setOpen] = useState(false);
const timer = useRef<number | undefined>(undefined);
const id = useId();
useEffect(() => () => window.clearTimeout(timer.current), []);
const openSoon = () => {
window.clearTimeout(timer.current);
timer.current = window.setTimeout(() => setOpen(true), open ? 0 : OPEN_DELAY);
};
const closeSoon = () => {
window.clearTimeout(timer.current);
timer.current = window.setTimeout(() => setOpen(false), CLOSE_DELAY);
};
return (
<span
className="relative inline-flex"
onPointerEnter={(e) => e.pointerType === "mouse" && openSoon()}
onPointerLeave={closeSoon}
onFocus={() => {
window.clearTimeout(timer.current);
setOpen(true);
}}
onBlur={(e) => {
if (!e.currentTarget.contains(e.relatedTarget)) closeSoon();
}}
onKeyDown={(e) => {
if (e.key === "Escape") setOpen(false);
}}
>
<span aria-describedby={open ? id : undefined} className="inline-flex">
{children}
</span>
<AnimatePresence>
{open ? (
<motion.div
id={id}
className={cn(
"absolute left-1/2 z-50 w-72 -translate-x-1/2 rounded-xl bg-popover p-4 text-popover-foreground shadow-overlay",
side === "top" ? "bottom-full mb-2" : "top-full mt-2",
className,
)}
style={{ originY: side === "top" ? 1 : 0 }}
initial={{ opacity: 0, y: reduce ? 0 : side === "top" ? 6 : -6, scale: reduce ? 1 : 0.97 }}
animate={{ opacity: 1, y: 0, scale: 1 }}
exit={{ opacity: 0, scale: reduce ? 1 : 0.98, transition: { duration: 0.1 } }}
transition={{ duration: 0.18, ease: [0.16, 1, 0.3, 1] }}
>
{content}
</motion.div>
) : null}
</AnimatePresence>
</span>
);
}States
- Waiting
- Opens after 600 ms, a little slower than a tooltip, since it covers more of the page.
- Open
- A card that grows from the trigger’s edge.
- Moving in
- A 150 ms grace period lets the pointer cross the gap, so links inside the card can be clicked.
- Keyboard
- Opens on focus and stays open while focus is inside the card. Escape closes it.
- Reduced motion
- Fades without growing.
Notes
Never put the only path to something in a hover card. Touch screens can’t hover, so the trigger should link to the full page.