Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
"use client";
/**
* Tooltip — Lightweight hover/focus tooltip component
*
* Renders a positioned tooltip on hover/focus with delayed reveal.
* Associates trigger and tooltip through aria-describedby for a11y.
*
* @module shared/components/Tooltip
*/
import type { ReactElement, ReactNode } from "react";
import {
cloneElement,
isValidElement,
useCallback,
useEffect,
useId,
useLayoutEffect,
useRef,
useState,
} from "react";
import { createPortal } from "react-dom";
interface TooltipProps {
children: ReactNode;
content?: ReactNode;
position?: "top" | "bottom" | "left" | "right";
className?: string;
tooltipClassName?: string;
delayMs?: number;
/**
* Issue #2352: Render the tooltip in a React portal so it escapes the
* stacking context of any ancestor with `overflow:hidden` / `overflow:auto`
* (modals, scroll containers). Without this, long labels next to a modal
* edge are clipped. Defaults to `true` because the previous absolute
* positioning has been the cause of every "tooltip cut off" report.
*/
usePortal?: boolean;
/**
* Allow the tooltip text to wrap onto multiple lines instead of forcing a
* single-line `whitespace-nowrap` layout. Use when the label is long.
*/
multiline?: boolean;
}
interface AriaDescribedElement {
"aria-describedby"?: string;
}
export default function Tooltip({
children,
content,
position = "top",
className = "",
tooltipClassName = "",
delayMs = 200,
usePortal = true,
multiline = false,
}: TooltipProps) {
const [visible, setVisible] = useState(false);
const tooltipId = useId();
const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
const wrapperRef = useRef<HTMLSpanElement | null>(null);
const tooltipRef = useRef<HTMLDivElement | null>(null);
const show = useCallback(() => {
clearTimeout(timeoutRef.current);
timeoutRef.current = setTimeout(() => setVisible(true), delayMs);
}, [delayMs]);
const hide = useCallback(() => {
clearTimeout(timeoutRef.current);
setVisible(false);
}, []);
useEffect(() => {
return () => {
clearTimeout(timeoutRef.current);
};
}, []);
// Position the portal-rendered tooltip relative to the trigger by writing
// directly to the DOM ref instead of round-tripping through React state.
// Touching .style here is the canonical React-portal positioning pattern
// and avoids the cascading-render warning we'd get from setCoords inside
// a layout effect.
useLayoutEffect(() => {
if (!visible || !usePortal) return;
const wrap = wrapperRef.current;
const tt = tooltipRef.current;
if (!wrap || !tt) return;
const rect = wrap.getBoundingClientRect();
const tRect = tt.getBoundingClientRect();
let top = 0;
let left = 0;
switch (position) {
case "bottom":
top = rect.bottom + 8;
left = rect.left + rect.width / 2 - tRect.width / 2;
break;
case "left":
top = rect.top + rect.height / 2 - tRect.height / 2;
left = rect.left - tRect.width - 8;
break;
case "right":
top = rect.top + rect.height / 2 - tRect.height / 2;
left = rect.right + 8;
break;
case "top":
default:
top = rect.top - tRect.height - 8;
left = rect.left + rect.width / 2 - tRect.width / 2;
break;
}
// Clamp horizontally inside the viewport so a trigger near the right
// edge does not produce a tooltip that bleeds off the screen.
const margin = 8;
const maxLeft = window.innerWidth - tRect.width - margin;
const minLeft = margin;
if (left > maxLeft) left = maxLeft;
if (left < minLeft) left = minLeft;
// Lock position immediately without any slide/flying animation from (0,0).
tt.style.transition = "none";
tt.style.top = `${top}px`;
tt.style.left = `${left}px`;
tt.style.visibility = "visible";
tt.style.opacity = "1";
}, [visible, usePortal, position, content]);
const positionClasses = {
top: "bottom-full left-1/2 -translate-x-1/2 mb-2",
bottom: "top-full left-1/2 -translate-x-1/2 mt-2",
left: "right-full top-1/2 -translate-y-1/2 mr-2",
right: "left-full top-1/2 -translate-y-1/2 ml-2",
};
const describedById = content ? tooltipId : undefined;
const trigger = isValidElement(children) ? (
(() => {
const child = children as ReactElement<AriaDescribedElement>;
const existingDescribedBy = child.props["aria-describedby"];
const mergedDescribedBy = [existingDescribedBy, describedById].filter(Boolean).join(" ");
return cloneElement(child, {
"aria-describedby": mergedDescribedBy || undefined,
});
})()
) : (
<span tabIndex={0} aria-describedby={describedById}>
{children}
</span>
);
const widthClass = multiline ? "max-w-xs whitespace-normal break-words" : "whitespace-nowrap";
const baseTooltipClass = `z-50 px-3 py-2 text-xs font-medium text-white bg-[#10141e]/95 rounded-lg shadow-xl pointer-events-none transition-opacity duration-150 motion-reduce:transition-none border border-white/10 backdrop-blur-sm ${tooltipClassName}`;
const portalEnabled = usePortal && typeof window !== "undefined";
const tooltipEl =
visible && content ? (
<div
ref={tooltipRef}
id={tooltipId}
role="tooltip"
className={
portalEnabled
? `fixed ${baseTooltipClass} ${widthClass}`
: `absolute ${baseTooltipClass} ${widthClass} ${positionClasses[position] || positionClasses.top}`
}
// For portal-rendered tooltips, mount hidden with opacity 0 at origin so
// layout effect sets the exact viewport coordinates before revealing it.
// This prevents the tooltip from flying or sliding in from top-left.
style={
portalEnabled ? { top: -9999, left: -9999, visibility: "hidden", opacity: 0 } : undefined
}
>
{content}
</div>
) : null;
return (
<span
ref={wrapperRef}
className={`relative inline-flex ${className}`}
onMouseEnter={show}
onMouseLeave={hide}
onFocus={show}
onBlur={hide}
onKeyDown={(event) => {
if (event.key === "Escape") hide();
}}
>
{trigger}
{portalEnabled && tooltipEl ? createPortal(tooltipEl, document.body) : tooltipEl}
</span>
);
}