4e:I[707087,["/_next/static/immutable/chunks/2985g-hklwiee.js","/_next/static/immutable/chunks/0qkc3dps_9x_i.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3thksmxn95rly.js","/_next/static/immutable/chunks/15bpbjna9-vr3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/0agonoz1szsjm.js","/_next/static/immutable/chunks/1ynd3dcge2kn1.js","/_next/static/immutable/chunks/0krdn-21gkgjt.js","/_next/static/immutable/chunks/0n9w9riw96l80.js","/_next/static/immutable/chunks/0w75qangey2ys.js","/_next/static/immutable/chunks/1tge7vcvsb70s.js","/_next/static/immutable/chunks/35ju_ac0ysz07.js"],"RegistryDependencies"] 4f:I[512940,["/_next/static/immutable/chunks/2985g-hklwiee.js","/_next/static/immutable/chunks/0qkc3dps_9x_i.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3thksmxn95rly.js","/_next/static/immutable/chunks/15bpbjna9-vr3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/0agonoz1szsjm.js","/_next/static/immutable/chunks/1ynd3dcge2kn1.js","/_next/static/immutable/chunks/0krdn-21gkgjt.js","/_next/static/immutable/chunks/0n9w9riw96l80.js","/_next/static/immutable/chunks/0w75qangey2ys.js","/_next/static/immutable/chunks/1tge7vcvsb70s.js","/_next/static/immutable/chunks/35ju_ac0ysz07.js"],"Installation"] 50:I[314491,["/_next/static/immutable/chunks/2985g-hklwiee.js","/_next/static/immutable/chunks/0qkc3dps_9x_i.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3thksmxn95rly.js","/_next/static/immutable/chunks/15bpbjna9-vr3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/0agonoz1szsjm.js","/_next/static/immutable/chunks/1ynd3dcge2kn1.js","/_next/static/immutable/chunks/0krdn-21gkgjt.js","/_next/static/immutable/chunks/0n9w9riw96l80.js","/_next/static/immutable/chunks/0w75qangey2ys.js","/_next/static/immutable/chunks/1tge7vcvsb70s.js","/_next/static/immutable/chunks/35ju_ac0ysz07.js"],"FilesView"] 51:T39f6,"use client"; import { useRef, useState, useCallback, useEffect, type Dispatch, type RefObject, type SetStateAction, } from "react"; export interface ItemRect { top: number; height: number; left: number; width: number; } interface UseProximityHoverOptions { /** * Which direction to resolve the nearest item along. * "y" — vertical lists (default): closest by top/height * "x" — horizontal strips: closest by left/width * "xy" — 2-D grids: closest card across both rows AND columns, * measured by Euclidean distance to each item's center */ axis?: "x" | "y" | "xy"; } interface UseProximityHoverReturn { activeIndex: number | null; setActiveIndex: Dispatch>; itemRects: ItemRect[]; /** * True once every registered item has been measured and no remeasure is * pending, i.e. `itemRects` describes the current item set. Gate absolutely * positioned overlays on it: an overlay that mounts against a rect a later * pass still corrects animates from the wrong place to the right one, which * reads as the highlight sliding in from another row. */ isMeasured: boolean; sessionRef: RefObject; handlers: { onMouseMove: (e: React.MouseEvent) => void; onMouseEnter: () => void; onMouseLeave: () => void; }; registerItem: (index: number, element: HTMLElement | null) => void; /** * Invalidates the published rects and runs the hook's coalesced measurement * pass again, holding `isMeasured` false until it settles. Reach for it when * something other than item registration invalidates layout — a popup that * stays mounted between opens keeps its items registered, so nothing else * would notice that its rects were taken while it was hidden. */ remeasure: () => void; measureItems: () => void; } /** * How many frames the coalesced remeasure retries while the registered items * still have no layout box. A popup can be in the DOM one frame before it is * laid out; retrying beats publishing zeroed rects, and the cap keeps a list * that stays hidden for good from spinning frames forever. */ const measurementAttempts = 3; export function useProximityHover( containerRef: RefObject, options: UseProximityHoverOptions = {} ): UseProximityHoverReturn { const { axis = "y" } = options; const itemsRef = useRef(new Map()); const [activeIndex, setActiveIndex] = useState(null); const [itemRects, setItemRects] = useState([]); const [isMeasured, setIsMeasured] = useState(false); const itemRectsRef = useRef([]); const sessionRef = useRef(0); const rafIdRef = useRef(null); const remeasureRafIdRef = useRef(null); /** * Publishes a rect for every registered item. Returns false when the * measurement could not be completed (no container, or an item without a * layout box) — nothing is published in that case, so the last complete * measurement stands instead of being overwritten with zeroes. */ const runMeasurement = useCallback(() => { const container = containerRef.current; if (!container) return false; const rects: ItemRect[] = []; let everyItemHasLayout = true; itemsRef.current.forEach((element, index) => { // An element inside a display:none / not-yet-laid-out popup has no // offsetParent and reports every offset as 0. Publishing that would pin // overlays to the top of the list, so treat the whole pass as // incomplete. A boxless element is the only case: `position: fixed` // items also have no offsetParent but do have a size. const hasLayoutBox = element.offsetParent !== null || element.offsetWidth > 0 || element.offsetHeight > 0; if (!hasLayoutBox) { everyItemHasLayout = false; return; } // Use offset* instead of getBoundingClientRect so measurements are // unaffected by CSS transforms (e.g. scaleY animation on the parent // motion.div). offsetTop/offsetLeft are layout values relative to the // offsetParent (the scroll container), matching the coordinate space // used by `position: absolute` children. rects[index] = { top: element.offsetTop, height: element.offsetHeight, left: element.offsetLeft, width: element.offsetWidth, }; }); if (!everyItemHasLayout) return false; // Skip the state update when nothing moved (a cheap top/left/width/height // compare) so redundant remeasures don't churn re-renders. const prev = itemRectsRef.current; let changed = prev.length !== rects.length; for (let i = 0; !changed && i < rects.length; i++) { const p = prev[i]; const r = rects[i]; if (p === r) continue; // both undefined (sparse slot) changed = !p || !r || p.top !== r.top || p.left !== r.left || p.width !== r.width || p.height !== r.height; } if (changed) { itemRectsRef.current = rects; setItemRects(rects); } return true; }, [containerRef]); const measureItems = useCallback(() => { runMeasurement(); }, [runMeasurement]); /** * The hook's single measurement pass: coalesces every trigger (item * registration, container resize) into one remeasure on the next frame and * is the only place readiness is reported, so `isMeasured` can never turn * true while another pass is still queued. */ const scheduleMeasurement = useCallback( (attemptsLeft: number) => { if (remeasureRafIdRef.current !== null) { cancelAnimationFrame(remeasureRafIdRef.current); } remeasureRafIdRef.current = requestAnimationFrame(() => { remeasureRafIdRef.current = null; if (runMeasurement()) { setIsMeasured(true); } else if (attemptsLeft > 1) { scheduleMeasurement(attemptsLeft - 1); } }); }, [runMeasurement] ); const remeasure = useCallback(() => { // Readiness drops first: until the pass below settles, the published rects // may not describe what is on screen, and an overlay positioned from them // would be corrected after mounting — which animates as a slide. setIsMeasured(false); scheduleMeasurement(measurementAttempts); }, [scheduleMeasurement]); // Observes the registered items themselves (not just the container): rows // that change size in place — e.g. the site-wide size step flipping while a // selection background is up — must invalidate the published rects even when // the container the effect below captured has since been remounted and the // ref points at a different element than the one being observed. const itemRoRef = useRef(null); const getItemRo = useCallback(() => { if (itemRoRef.current === null && typeof ResizeObserver !== "undefined") { itemRoRef.current = new ResizeObserver(() => scheduleMeasurement(measurementAttempts) ); } return itemRoRef.current; }, [scheduleMeasurement]); const registerItem = useCallback( (index: number, element: HTMLElement | null) => { if (element) { itemsRef.current.set(index, element); getItemRo()?.observe(element); } else { const previous = itemsRef.current.get(index); if (previous) itemRoRef.current?.unobserve(previous); itemsRef.current.delete(index); } // Coalesce rapid register/unregister calls (e.g. when an AnimatePresence // remounts a list of rows) into a single remeasure on the next frame, // so consumers don't have to manually call measureItems after the // container's children swap. remeasure(); }, [remeasure, getItemRo] ); const handleMouseMove = useCallback( (e: React.MouseEvent) => { const mouseX = e.clientX; const mouseY = e.clientY; if (rafIdRef.current !== null) { cancelAnimationFrame(rafIdRef.current); } rafIdRef.current = requestAnimationFrame(() => { rafIdRef.current = null; const container = containerRef.current; if (!container) return; const containerRect = container.getBoundingClientRect(); // ── 2-D grid path ────────────────────────────────────────── // When items wrap into rows and columns, a single-axis nearest // pick can't tell which card the cursor is closest to. Resolve // by Euclidean distance to each item's center, and prefer any // item the cursor is actually inside (point-in-rect). if (axis === "xy") { let closestIndex: number | null = null; let closestDistance = Infinity; let containingIndex: number | null = null; const rects = itemRectsRef.current; const scrollX = container.scrollLeft; const scrollY = container.scrollTop; const borderX = container.clientLeft; const borderY = container.clientTop; // Map layout coords into visual/viewport space, accounting for any // cumulative ancestor transform: scale (see the single-axis note // below). X and Y scale independently. const scaleX = container.offsetWidth > 0 ? containerRect.width / container.offsetWidth : 1; const scaleY = container.offsetHeight > 0 ? containerRect.height / container.offsetHeight : 1; for (let index = 0; index < rects.length; index++) { const r = rects[index]; if (!r) continue; const left = containerRect.left + (borderX + r.left - scrollX) * scaleX; const top = containerRect.top + (borderY + r.top - scrollY) * scaleY; const width = r.width * scaleX; const height = r.height * scaleY; if ( mouseX >= left && mouseX <= left + width && mouseY >= top && mouseY <= top + height ) { containingIndex = index; } const dx = mouseX - (left + width / 2); const dy = mouseY - (top + height / 2); const distance = Math.hypot(dx, dy); if (distance < closestDistance) { closestDistance = distance; closestIndex = index; } } setActiveIndex(containingIndex ?? closestIndex); return; } const mousePos = axis === "x" ? mouseX : mouseY; let closestIndex: number | null = null; let closestDistance = Infinity; let containingIndex: number | null = null; const rects = itemRectsRef.current; // Convert content-relative rects to viewport coords using live scroll const scrollOffset = axis === "x" ? container.scrollLeft : container.scrollTop; const borderOffset = axis === "x" ? container.clientLeft : container.clientTop; const containerEdge = axis === "x" ? containerRect.left : containerRect.top; // Item rects are layout values (offset*); the container's bounding rect // reflects any cumulative ancestor transform: scale. Compute the scale // factor so we can map layout coords into the same visual viewport // space the mouse cursor lives in. const layoutSize = axis === "x" ? container.offsetWidth : container.offsetHeight; const visualSize = axis === "x" ? containerRect.width : containerRect.height; const scale = layoutSize > 0 ? visualSize / layoutSize : 1; for (let index = 0; index < rects.length; index++) { const r = rects[index]; if (!r) continue; const contentPos = axis === "x" ? r.left : r.top; const itemStart = containerEdge + (borderOffset + contentPos - scrollOffset) * scale; const itemSize = (axis === "x" ? r.width : r.height) * scale; const itemEnd = itemStart + itemSize; if (mousePos >= itemStart && mousePos <= itemEnd) { containingIndex = index; } const itemCenter = itemStart + itemSize / 2; const distance = Math.abs(mousePos - itemCenter); if (distance < closestDistance) { closestDistance = distance; closestIndex = index; } } setActiveIndex(containingIndex ?? closestIndex); }); }, [axis, containerRef] ); const handleMouseEnter = useCallback(() => { sessionRef.current += 1; }, []); const handleMouseLeave = useCallback(() => { if (rafIdRef.current !== null) { cancelAnimationFrame(rafIdRef.current); rafIdRef.current = null; } setActiveIndex(null); }, []); // Remeasure when the container resizes — a reflow moves items even though // the registered set is unchanged, which would otherwise leave itemRects // stale. Coalesced through the same rAF as register/unregister. Readiness is // deliberately not dropped: the item set is unchanged, so the published rects // stay usable, and hiding overlays on every reflow would flicker them. useEffect(() => { const container = containerRef.current; if (!container || typeof ResizeObserver === "undefined") return; const ro = new ResizeObserver(() => scheduleMeasurement(measurementAttempts)); ro.observe(container); return () => ro.disconnect(); }, [containerRef, scheduleMeasurement]); // Clean up rAF and the item observer on unmount useEffect(() => { return () => { if (rafIdRef.current !== null) { cancelAnimationFrame(rafIdRef.current); } if (remeasureRafIdRef.current !== null) { cancelAnimationFrame(remeasureRafIdRef.current); } itemRoRef.current?.disconnect(); itemRoRef.current = null; }; }, []); return { activeIndex, setActiveIndex, itemRects, isMeasured, sessionRef, handlers: { onMouseMove: handleMouseMove, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, }, registerItem, remeasure, measureItems, }; } /** * Hook for child items to register themselves with the proximity hover system. * Call in useEffect with the item's ref and index. */ export function useRegisterProximityItem( registerItem: (index: number, element: HTMLElement | null) => void, index: number, ref: RefObject ) { useEffect(() => { registerItem(index, ref.current); return () => registerItem(index, null); }, [index, registerItem, ref]); } 4a:["$","div",null,{"className":"flex flex-col gap-12","children":[["$","div",null,{"className":"pt-10 flex flex-col gap-4","children":[["$","ul",null,{"className":"flex gap-2 flex-wrap","children":[]}],["$","$L4e",null,{"registryDependencies":[]}]]}],["$","$L4f",null,{"sourceUrl":"https://www.fluidfunctionalism.com/r/use-proximity-hover.json","proxyUrl":"https://shadcnregistry.com/r/fluid/use-proximity-hover","itemId":"@fluid/use-proximity-hover"}],["$","section",null,{"className":"flex flex-col gap-4","id":"files","children":[["$","h2",null,{"className":"text-lg md:text-2xl font-bold font-mono","children":"Files"}],["$","$L50",null,{"files":[{"path":"registry/default/hooks/use-proximity-hover.ts","content":"$51","type":"registry:hook"}]}]]}],"$L52"]}]

UseProximityHover

Installation

Files

hooks

Styles