Ensure ref is always connected when rendering in Portal (#3789)

This PR fixes an issue where elements of a `<Portal />` were not
connected on subsequent renders.

Our Portal component is relatively complex because we want to make sure
we use the correct `document`, only keep a single portal root (and clean
it up when there are no more portals) and each portal gets its own `<div
data-headlessui-portal>`.

This is also where the bug was, because we were creating the
`data-headlessui-portal` div manually.

Cleaning all that up, and let React take care of most of that fixes the
issue as well.

## Test plan

1. All existing tests pass
2. Elements are now connected on subsequent renders, verified using the
reproduction steps in #3681

Before:



https://github.com/user-attachments/assets/28dde5de-505e-4f2c-bf34-2feb4fe8fac7


After:



https://github.com/user-attachments/assets/d54cfa6a-8d86-47e7-9c5b-dbc620a86ef8


Fixes: #3681

Author: RobinMalfait

packages/@headlessui-react/CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Ensure pressing `Tab` in the `ComboboxInput`, correctly syncs the input value ([#3785](https://github.com/tailwindlabs/headlessui/pull/3785))
 - Ensure `--button-width` and `--input-width` have the latest value ([#3786](https://github.com/tailwindlabs/headlessui/pull/3786))
 - Fix 'Invalid prop `data-headlessui-state` supplied to `React.Fragment`' warning ([#3788](https://github.com/tailwindlabs/headlessui/pull/3788))
+- Ensure `element` in `ref` callback is always connected when rendering in a `Portal` ([#3789](https://github.com/tailwindlabs/headlessui/pull/3789))
 
 ## [2.2.7] - 2025-07-30
 

packages/@headlessui-react/src/components/portal/portal.tsx

@@ -14,15 +14,13 @@ import React, {
   type Ref,
 } from 'react'
 import { createPortal } from 'react-dom'
+import { useDisposables } from '../../hooks/use-disposables'
 import { useEvent } from '../../hooks/use-event'
-import { useIsoMorphicEffect } from '../../hooks/use-iso-morphic-effect'
 import { useOnUnmount } from '../../hooks/use-on-unmount'
 import { useOwnerDocument } from '../../hooks/use-owner'
-import { useServerHandoffComplete } from '../../hooks/use-server-handoff-complete'
 import { optionalRef, useSyncRefs } from '../../hooks/use-sync-refs'
 import { usePortalRoot } from '../../internal/portal-force-root'
 import type { Props } from '../../types'
-import * as DOM from '../../utils/dom'
 import { env } from '../../utils/env'
 import { forwardRefWithAs, useRender, type HasDisplayName, type RefProp } from '../../utils/render'
 
@@ -94,58 +92,43 @@ let InternalPortalFn = forwardRefWithAs(function InternalPortalFn<
   let defaultOwnerDocument = useOwnerDocument(internalPortalRootRef)
   let ownerDocument = incomingOwnerDocument ?? defaultOwnerDocument
   let target = usePortalTarget(ownerDocument)
-  let [element] = useState<HTMLDivElement | null>(() =>
-    env.isServer ? null : ownerDocument?.createElement('div') ?? null
-  )
   let parent = useContext(PortalParentContext)
-  let ready = useServerHandoffComplete()
-
-  useIsoMorphicEffect(() => {
-    if (!target || !element) return
-
-    // Element already exists in target, always calling target.appendChild(element) will cause a
-    // brief unmount/remount.
-    if (!target.contains(element)) {
-      element.setAttribute('data-headlessui-portal', '')
-      target.appendChild(element)
-    }
-  }, [target, element])
-
-  useIsoMorphicEffect(() => {
-    if (!element) return
-    if (!parent) return
-
-    return parent.register(element)
-  }, [parent, element])
+  let d = useDisposables()
+  let render = useRender()
 
   useOnUnmount(() => {
-    if (!target || !element) return
-
-    if (DOM.isNode(element) && target.contains(element)) {
-      target.removeChild(element)
-    }
+    if (!target) return
 
+    // Cleanup the portal root when all portals are unmounted
     if (target.childNodes.length <= 0) {
       target.parentElement?.removeChild(target)
     }
   })
 
-  let render = useRender()
-  if (!ready) return null
-
   let ourProps = { ref: portalRef }
 
-  return !target || !element
+  return !target
     ? null
     : createPortal(
-        render({
-          ourProps,
-          theirProps,
-          slot: {},
-          defaultTag: DEFAULT_PORTAL_TAG,
-          name: 'Portal',
-        }),
-        element
+        <div
+          data-headlessui-portal=""
+          ref={(el) => {
+            d.dispose()
+
+            if (parent && el) {
+              d.add(parent.register(el))
+            }
+          }}
+        >
+          {render({
+            ourProps,
+            theirProps,
+            slot: {},
+            defaultTag: DEFAULT_PORTAL_TAG,
+            name: 'Portal',
+          })}
+        </div>,
+        target
       )
 })