ui/hooks/floating-position

Floating Position

hookpositioningfloatingpopovertooltip

Position floating content relative to a trigger element. Handles collision detection, auto-flipping to opposite sides, and viewport boundary shifting.

tsx

1 const triggerRef = useRef<HTMLButtonElement>(null);2 const { position, contentRef } = useFloatingPosition({3   triggerRef,4   open,5   side: "bottom",6   align: "center",7 });

Installation

$pnpm exec dgadd add ui/floating-position

[Installs to]src/hooks/use-floating-position.ts[Item]ui/floating-position

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Parameters

Name	Type	Default	Description
triggerRefrequired	RefObject<HTMLElement \| null>	—	Ref to the trigger element that the floating content is positioned relative to.
openrequired	boolean	—	Whether the floating content is open. Position is computed when true, reset to null when false.
side	"top" \| "bottom" \| "left" \| "right"	"top"	Preferred side for positioning. Auto-flips if there isn't enough space.
align	"start" \| "center" \| "end"	"center"	Alignment along the cross axis.
sideOffset	number	6	Distance in pixels between the trigger and floating content along the side axis.
alignOffset	number	0	Offset in pixels along the alignment axis.
collisionPadding	number	8	Minimum distance in pixels from viewport edges when avoiding collisions.
avoidCollisions	boolean	true	Whether to automatically flip sides and shift position to stay within viewport.

Returns

UseFloatingPositionReturnObject containing computed position and a ref for the floating content element.

Name	Type	Default	Description
positionrequired	FloatingPosition \| null	—	Computed position with x, y coordinates and resolved side/align. Null when closed.
contentRefrequired	RefCallback<HTMLDivElement>	—	Callback ref to attach to the floating content element. Attaching, replacing, or removing the node restarts measurement and observer subscriptions.

Examples

Basic Positioning

Preview

tsx

1 "use client";2 3 import { useRef, useState } from "react";4 import { useFloatingPosition } from "@/hooks/use-floating-position";5 6 export default function FloatingPositionBasicExample() {7   const [open, setOpen] = useState(false);8   const triggerRef = useRef<HTMLButtonElement>(null);9   const { position, contentRef } = useFloatingPosition({10     triggerRef,11     open,12     side: "bottom",13     align: "start",14   });15 16   return (17     <div className="relative py-12">18       <button19         type="button"20         ref={triggerRef}21         onClick={() => setOpen((v) => !v)}22         className="font-mono text-sm border border-border px-3 py-1.5 bg-background hover:bg-muted transition-colors"23       >24         {open ? "Close" : "Open"} floating25       </button>26 27       {open && (28         <div29           ref={contentRef}30           data-anchor-hidden={position?.anchorHidden ? "" : undefined}31           style={32             position33               ? {34                   position: "fixed",35                   left: position.x,36                   top: position.y,37                   ...(position.anchorHidden38                     ? { opacity: 0, pointerEvents: "none" as const, animation: "none" }39                     : null),40                 }41               : { position: "fixed", opacity: 0 }42           }43           className="z-[var(--z-popover)] w-48 rounded-sm border border-border bg-background p-3 font-mono text-sm"44         >45           <p className="text-foreground">Floating content</p>46           <p className="text-muted-foreground text-xs mt-1">47             Side: {position?.side ?? "—"} · Align: {position?.align ?? "—"}48           </p>49         </div>50       )}51     </div>52   );53 }54

Notes

Collision Detection

When content would overflow the viewport, the hook tries the opposite side first, then cross-axis sides, and finally shifts the position to stay within bounds.

Layout Effect

Uses useLayoutEffect to compute position synchronously before paint, preventing visual flicker.

Late Attachment

The content callback ref participates in the positioning lifecycle, so content mounted after the overlay opens is measured immediately and receives resize and scroll subscriptions.

Used By

Built into PopoverContent for automatic positioning of popovers and tooltips.

Source

Highlighted source loads after this disclosure opens. Browse the source repository.