{"slug":"tooltip","name":"Tooltip","description":"Hover or focus tooltip with blur enter/exit and spring spawn, plus a Morph variant where one shared bubble glides and resizes between neighboring triggers.","category":"motion","source_url":"https://ui-lab-ten.vercel.app/r/tooltip/raw","detail_url":"https://ui-lab-ten.vercel.app/r/tooltip","raw_url":"https://ui-lab-ten.vercel.app/r/tooltip/raw","page_url":"https://ui-lab-ten.vercel.app/components/motion/tooltip","dependencies":["clsx","lucide-react","motion","react","react-dom","tailwind-merge"],"internal":["@/components/motion/tooltip","@/lib/ease","@/lib/hooks/use-hover-capable","@/lib/utils"],"files":[{"path":"components/motion/tooltip.tsx","type":"component","content":"\"use client\";\n// ui-lab-ten.vercel.app/components/motion/tooltip\n\nimport {\n  AnimatePresence,\n  motion,\n  useReducedMotion,\n  type Variants,\n} from \"motion/react\";\nimport {\n  cloneElement,\n  isValidElement,\n  type ReactElement,\n  type ReactNode,\n  useCallback,\n  useEffect,\n  useId,\n  useMemo,\n  useRef,\n  useState,\n} from \"react\";\nimport { createPortal } from \"react-dom\";\nimport { EASE_OUT } from \"@/lib/ease\";\nimport { useHoverCapable } from \"@/lib/hooks/use-hover-capable\";\nimport { cn } from \"@/lib/utils\";\n\ntype Side = \"top\" | \"right\" | \"bottom\" | \"left\";\n\nexport interface TooltipProps {\n  content: ReactNode;\n  children: ReactElement;\n  side?: Side;\n  /** Delay before showing (ms). Default 120. */\n  delay?: number;\n  className?: string;\n  /** Classes for the outer wrapper span. Use to fix baseline / fill parent. */\n  wrapperClassName?: string;\n}\n\n// Gap between trigger and tooltip, in px.\nconst GAP = 8;\n\n// Centering transform for the fixed-positioned anchor point, per side.\nconst anchorTransform: Record<Side, string> = {\n  top: \"translate(-50%, -100%)\",\n  bottom: \"translate(-50%, 0)\",\n  left: \"translate(-100%, -50%)\",\n  right: \"translate(0, -50%)\",\n};\n\nconst transformOrigin: Record<Side, string> = {\n  top: \"center bottom\",\n  bottom: \"center top\",\n  left: \"right center\",\n  right: \"left center\",\n};\n\n// Offset is in the direction *away* from the trigger — content originates near\n// the trigger and rises into resting position.\nconst offsetFrom: Record<Side, { x?: number; y?: number }> = {\n  top: { y: 8 },\n  bottom: { y: -8 },\n  left: { x: 8 },\n  right: { x: -8 },\n};\n\nfunction buildVariants(side: Side): Variants {\n  const o = offsetFrom[side];\n  return {\n    initial: {\n      opacity: 0,\n      scale: 0.9,\n      filter: \"blur(5px)\",\n      x: o.x ?? 0,\n      y: o.y ?? 0,\n    },\n    animate: {\n      opacity: 1,\n      scale: 1,\n      filter: \"blur(0px)\",\n      x: 0,\n      y: 0,\n      transition: {\n        type: \"spring\",\n        stiffness: 380,\n        damping: 30,\n        mass: 0.7,\n        opacity: { duration: 0.14, ease: EASE_OUT },\n        filter: { duration: 0.18, ease: EASE_OUT },\n      },\n    },\n    exit: {\n      opacity: 0,\n      scale: 0.94,\n      filter: \"blur(3px)\",\n      x: (o.x ?? 0) * 0.6,\n      y: (o.y ?? 0) * 0.6,\n      transition: { duration: 0.12, ease: EASE_OUT },\n    },\n  };\n}\n\nconst REDUCED_VARIANTS: Variants = {\n  initial: { opacity: 0 },\n  animate: { opacity: 1, transition: { duration: 0.14, ease: EASE_OUT } },\n  exit: { opacity: 0, transition: { duration: 0.1, ease: EASE_OUT } },\n};\n\n// Once any tooltip has just closed, neighbouring tooltips open without the\n// initial delay — moving along a toolbar feels instant after the first one.\nconst WARM_WINDOW_MS = 300;\nlet lastHiddenAt = 0;\n\nexport function Tooltip({\n  content,\n  children,\n  side = \"top\",\n  delay = 120,\n  className,\n  wrapperClassName,\n}: TooltipProps) {\n  const [open, setOpen] = useState(false);\n  const [coords, setCoords] = useState<{ top: number; left: number } | null>(\n    null,\n  );\n  const id = useId();\n  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);\n  const anchorRef = useRef<HTMLSpanElement>(null);\n  const reduce = useReducedMotion();\n  const canHover = useHoverCapable();\n\n  // Anchor point in viewport coords, on the edge of the trigger facing `side`.\n  // Position:fixed means these viewport coords place the tooltip directly, so\n  // it escapes every ancestor's stacking context and overflow.\n  const place = useCallback(() => {\n    const el = anchorRef.current;\n    if (!el) return;\n    const r = el.getBoundingClientRect();\n    const cx = r.left + r.width / 2;\n    const cy = r.top + r.height / 2;\n    const point: Record<Side, { top: number; left: number }> = {\n      top: { top: r.top - GAP, left: cx },\n      bottom: { top: r.bottom + GAP, left: cx },\n      left: { top: cy, left: r.left - GAP },\n      right: { top: cy, left: r.right + GAP },\n    };\n    setCoords(point[side]);\n  }, [side]);\n\n  const show = useCallback(() => {\n    if (!canHover) return;\n    if (timer.current) clearTimeout(timer.current);\n    const warm = Date.now() - lastHiddenAt < WARM_WINDOW_MS;\n    timer.current = setTimeout(\n      () => {\n        place();\n        setOpen(true);\n      },\n      warm ? 0 : delay,\n    );\n  }, [canHover, delay, place]);\n\n  const hide = useCallback(() => {\n    if (timer.current) {\n      clearTimeout(timer.current);\n      timer.current = null;\n    }\n    setOpen((wasOpen) => {\n      if (wasOpen) lastHiddenAt = Date.now();\n      return false;\n    });\n  }, []);\n\n  // Keep the tooltip pinned to the trigger while it's open and the page scrolls\n  // or resizes (fixed coords are viewport-relative).\n  useEffect(() => {\n    if (!open) return;\n    const onMove = () => place();\n    window.addEventListener(\"scroll\", onMove, true);\n    window.addEventListener(\"resize\", onMove);\n    return () => {\n      window.removeEventListener(\"scroll\", onMove, true);\n      window.removeEventListener(\"resize\", onMove);\n    };\n  }, [open, place]);\n\n  const variants = useMemo(\n    () => (reduce ? REDUCED_VARIANTS : buildVariants(side)),\n    [reduce, side],\n  );\n\n  if (!isValidElement(children)) return children;\n\n  const trigger = cloneElement(\n    children as ReactElement<Record<string, unknown>>,\n    {\n      onMouseEnter: show,\n      onMouseLeave: hide,\n      onFocus: show,\n      onBlur: hide,\n      \"aria-describedby\": id,\n    },\n  );\n\n  return (\n    <>\n      <span\n        ref={anchorRef}\n        className={cn(\"relative inline-flex align-middle\", wrapperClassName)}\n      >\n        {trigger}\n      </span>\n      {typeof document !== \"undefined\"\n        ? createPortal(\n            <AnimatePresence>\n              {open && coords ? (\n                <span\n                  aria-hidden\n                  className=\"pointer-events-none fixed z-[9999]\"\n                  style={{\n                    top: coords.top,\n                    left: coords.left,\n                    transform: anchorTransform[side],\n                  }}\n                >\n                  <motion.span\n                    id={id}\n                    role=\"tooltip\"\n                    variants={variants}\n                    initial=\"initial\"\n                    animate=\"animate\"\n                    exit=\"exit\"\n                    style={{\n                      transformOrigin: transformOrigin[side],\n                      willChange: \"transform, opacity\",\n                    }}\n                    className={cn(\n                      \"block whitespace-nowrap rounded-lg border border-border bg-background px-2.5 py-1 text-xs font-medium text-foreground shadow-lg\",\n                      className,\n                    )}\n                  >\n                    {content}\n                  </motion.span>\n                </span>\n              ) : null}\n            </AnimatePresence>,\n            document.body,\n          )\n        : null}\n    </>\n  );\n}\n"},{"path":"lib/ease.ts","type":"util","content":"// Shared motion tokens. Easing curves mirror the CSS custom properties in\n// globals.css; springs are the canonical physics used across components.\n// Strong custom variants — defaults like `ease-in`/`ease-out` feel weak.\n\nexport const EASE_OUT = [0.16, 1, 0.3, 1] as const;\nexport const EASE_IN_OUT = [0.77, 0, 0.175, 1] as const;\nexport const EASE_DRAWER = [0.32, 0.72, 0, 1] as const;\n\n/** CSS string form of EASE_OUT for inline style transitions. */\nexport const EASE_OUT_CSS = \"cubic-bezier(0.16, 1, 0.3, 1)\";\n\n/** Press feedback on buttons and other tappable surfaces. */\nexport const SPRING_PRESS = {\n  type: \"spring\",\n  stiffness: 500,\n  damping: 30,\n  mass: 0.6,\n} as const;\n\n/** Content swaps — label/icon slots trading places inside a control. */\nexport const SPRING_SWAP = {\n  type: \"spring\",\n  stiffness: 460,\n  damping: 30,\n  mass: 0.55,\n} as const;\n\n/** Overlay panel entrances — modals and sheets summoned by pointer. */\nexport const SPRING_PANEL = {\n  type: \"spring\",\n  stiffness: 420,\n  damping: 40,\n  mass: 0.5,\n} as const;\n\n/** Shared-layout glides — pills, indicators and panels morphing between positions. */\nexport const SPRING_LAYOUT = {\n  type: \"spring\",\n  stiffness: 360,\n  damping: 32,\n  mass: 0.6,\n} as const;\n\n/** Cursor-follow physics for decorative mouse tracking (magnetic, tilt, dock). */\nexport const SPRING_MOUSE = {\n  stiffness: 200,\n  damping: 15,\n  mass: 0.3,\n} as const;\n"},{"path":"lib/hooks/use-hover-capable.ts","type":"util","content":"\"use client\";\n\nimport { useEffect, useState } from \"react\";\n\n/**\n * Returns true only on devices that have a true hover (mouse / trackpad).\n * Touch devices fire phantom `:hover` on tap that sticks until tap-elsewhere\n * — gate hover-only effects (scale lifts, magnetic pulls) behind this.\n */\nexport function useHoverCapable() {\n  const [canHover, setCanHover] = useState(false);\n\n  useEffect(() => {\n    if (typeof window === \"undefined\" || !window.matchMedia) return;\n    const mq = window.matchMedia(\"(hover: hover) and (pointer: fine)\");\n    const update = () => setCanHover(mq.matches);\n    update();\n    mq.addEventListener?.(\"change\", update);\n    return () => mq.removeEventListener?.(\"change\", update);\n  }, []);\n\n  return canHover;\n}\n"},{"path":"lib/utils.ts","type":"util","content":"import { clsx, type ClassValue } from \"clsx\"\nimport { twMerge } from \"tailwind-merge\"\n\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs))\n}\n"},{"path":"components/previews/motion/tooltip.preview.tsx","type":"preview","content":"\"use client\";\n\nimport { Heart, Settings, Share, Trash2 } from \"lucide-react\";\nimport { Tooltip } from \"@/components/motion/tooltip\";\n\nexport function TooltipPreview() {\n  return (\n    <div className=\"flex flex-col items-center gap-12\">\n      <div className=\"flex flex-wrap items-center justify-center gap-4\">\n        <Tooltip content=\"Like this post\" side=\"top\">\n          <button type=\"button\" className=\"inline-flex h-10 w-10 items-center justify-center rounded-full border border-border bg-card text-foreground press\">\n            <Heart className=\"h-4 w-4\" />\n          </button>\n        </Tooltip>\n        <Tooltip content=\"Share\" side=\"bottom\">\n          <button type=\"button\" className=\"inline-flex h-10 w-10 items-center justify-center rounded-full border border-border bg-card text-foreground press\">\n            <Share className=\"h-4 w-4\" />\n          </button>\n        </Tooltip>\n        <Tooltip content=\"Open settings\" side=\"left\">\n          <button type=\"button\" className=\"inline-flex h-10 w-10 items-center justify-center rounded-full border border-border bg-card text-foreground press\">\n            <Settings className=\"h-4 w-4\" />\n          </button>\n        </Tooltip>\n        <Tooltip content=\"Move to trash\" side=\"right\">\n          <button type=\"button\" className=\"inline-flex h-10 w-10 items-center justify-center rounded-full border border-border bg-card text-foreground press\">\n            <Trash2 className=\"h-4 w-4\" />\n          </button>\n        </Tooltip>\n      </div>\n      <p className=\"text-xs text-muted-foreground\">Hover or focus each button. Content fades and un-blurs in.</p>\n    </div>\n  );\n}\n"}]}