react-floating-ui

React 19 + Floating UI — Project Conventions & Pitfalls

This project uses React 19.2, @floating-ui/react 0.27, daisyUI 5, and Tailwind CSS 4.

---

1. React 19: ref Is a Regular Prop (CRITICAL)

In React 19, ref moved from a special element field into element.props.ref. This breaks the common cloneElement + spread pattern silently.

The Bug

// ❌ BROKEN in React 19 — child.props.ref overwrites our ref
cloneElement(child, {
  ref: ourMergedRef,       // set first...
  ...child.props           // ...overwritten by child.props.ref!
})

The Fix

// ✅ CORRECT — strip ref, place merged ref LAST
const { ref: _, ...propsWithoutRef } = child.props ?? {}
cloneElement(child, getReferenceProps({
  ...propsWithoutRef,
  ref: mergedRef  // MUST come last to take precedence
}))

Reading a Child's Ref (React 18 + 19 compatible)

// Read from both locations for cross-version compatibility
const childRef = isValidElement(children)
  ? (children as any).props?.ref ?? (children as any).ref ?? null
  : null

Where This Applies

• Tooltip.tsx — wraps arbitrary children via cloneElement
• Popover.tsx — PopoverTrigger asChild uses cloneElement
• Any component using cloneElement with useMergeRefs

---

2. Floating UI: Use Built-in Interaction Hooks

Rule

NEVER reinvent hover/click/focus with manual useState + setTimeout. ALWAYS use Floating UI's interaction hooks.

Interaction	Hook	Example
Hover	useHover(context, opts)	Tooltip, HoverMenu
Click	useClick(context, opts)	Popover, Select
Dismiss	useDismiss(context)	All floating components
Role	useRole(context, { role })	All (a11y)
Focus	useFocus(context)	Tooltip (keyboard a11y)

Why

Manual hover state management bypasses Floating UI's onOpenChange flow. This causes useDismiss, whileElementsMounted, and position calculation to be disconnected from the actual open state.