Tooltip
96 lines · 1 file · MIT
A small label on hover or focus; neighbours open at once after the first.
3 days ago
import { Tooltip as BaseTooltip } from "@base-ui/react/tooltip";
import { useRef, useState, type ReactElement, type ReactNode } from "react";
import { cn } from "./cn";
/**
* Tooltips that sit side by side, like the folded sidebar's icons: the first
* waits a moment, so passing through does not flash one, and once one is up
* its neighbours open at once, with no animation, as the pointer moves along.
* Mark the tooltips inside it `grouped`.
*/
export function TooltipGroup({ children }: { children: ReactNode }) {
return (
<BaseTooltip.Provider delay={350} closeDelay={0} timeout={400}>
{children}
</BaseTooltip.Provider>
);
}
/** Delays for a tooltip on its own; a TooltipGroup sets them for its members. */
const ALONE = { delay: 40, closeDelay: 120 };
const POPUP =
"max-w-xs origin-[var(--transform-origin)] rounded-md bg-surface-2 px-2.5 py-1.5 text-xs text-text transition-[opacity,scale] duration-125 ease-out smooth-shadow-ring-sm data-[ending-style]:opacity-0 data-[instant]:duration-0 data-[starting-style]:scale-[0.97] data-[starting-style]:opacity-0 motion-reduce:transition-none";
/** A label in a row of them goes the moment the pointer leaves: a fade there
* trails behind somebody already looking elsewhere. */
const GROUPED_POPUP = "data-[ending-style]:duration-0";
export function Tooltip({
content,
children,
side,
grouped,
guard,
}: {
/** Empty (undefined, null or "") shows no tooltip at all. */
content?: ReactNode;
children: ReactElement;
/** Where it opens; Base UI's default is above. */
side?: "top" | "right" | "bottom" | "left";
/** Inside a TooltipGroup, which sets the delays for all of them. */
grouped?: boolean;
/** Opens only when this says yes for the trigger, checked as the pointer
* enters or focus lands. OverflowTip uses it to skip text that fits. */
guard?: (trigger: HTMLElement) => boolean;
}) {
const triggerRef = useRef<HTMLButtonElement | null>(null);
const [open, setOpen] = useState(false);
const guarded = guard
? {
open,
onOpenChange: (next: boolean) =>
setOpen(next && triggerRef.current !== null && guard(triggerRef.current)),
}
: {};
// Nothing to say, nothing to show: the child as it is.
if (content === undefined || content === null || content === "") return children;
const root = (
<BaseTooltip.Root {...guarded}>
{/* Base UI waits 600ms by default, which is tuned for tooltips that
repeat a control's own label. Ours carry advice you cannot get any
other way, so waiting to be sure somebody meant it costs more than
showing it to somebody passing through. */}
{/* closeDelay, because the trigger is a 13px mark and the pointer
wobbles: leaving instantly meant a sweep across it started a close,
re-entered, and started again, so the fade stuttered instead of
running once. A tenth of a second absorbs that and is still gone
before anyone reads it as lag. */}
<BaseTooltip.Trigger ref={triggerRef} {...(grouped ? {} : ALONE)} render={children} />
<BaseTooltip.Portal>
{/* Above every dialog, the nested ones (z-[70]) included: a tooltip
is transient and always explains what is on top of it. */}
<BaseTooltip.Positioner side={side} sideOffset={6} className="z-[100]">
{/* It grows out of the mark that opened it, rather than out of
its own middle: --transform-origin is the anchor's side, so a
tip above a control expands downward toward it and one below
expands upward. 125ms and ease-out, fast enough to keep out of
the way and decelerating so it settles rather than stops.
Scale 0.97, because a tooltip is small and anything deeper
reads as a pop. It fades out without the scale: an exit can
still be cut short by the pointer coming back, and a size
snapping mid-flight is far more visible than an opacity one.
data-instant is Base UI saying this one was not opened by
hovering (keyboard focus, or a second tip while one is already
up), where an animation is a delay nobody asked for. */}
<BaseTooltip.Popup className={cn(POPUP, grouped && GROUPED_POPUP)}>
{content}
</BaseTooltip.Popup>
</BaseTooltip.Positioner>
</BaseTooltip.Portal>
</BaseTooltip.Root>
);
return grouped ? root : <BaseTooltip.Provider>{root}</BaseTooltip.Provider>;
}
Install
One command. The files land in your repo, with everything they import.
$ bunx shadcn@latest add @blocco/tooltip- Category
- Overlays
- Files
- tooltip.tsx
- Brings in
- @base-ui/react