Don’t render <Portal>s while hydrating (#3825)

We're currently rendering the portal target element when hydrating. This
breaks SSR when using portals. We need to *not* render portals during
hydration since portals (even the wrapper target) are not renderable on
the server.

Fixes #3824

cc @RobinMalfait

Author: thecrypticace

packages/@headlessui-react/CHANGELOG.md

@@ -7,7 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-- Nothing yet!
+### Fixed
+
+- Don’t render `<Portal>` while hydrating ([#3825](https://github.com/tailwindlabs/headlessui/pull/3825))
 
 ## [2.2.9] - 2025-09-25
 

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

@@ -18,6 +18,7 @@ import { useDisposables } from '../../hooks/use-disposables'
 import { useEvent } from '../../hooks/use-event'
 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'
@@ -94,6 +95,7 @@ let InternalPortalFn = forwardRefWithAs(function InternalPortalFn<
   let target = usePortalTarget(ownerDocument)
   let parent = useContext(PortalParentContext)
   let d = useDisposables()
+  let ready = useServerHandoffComplete()
   let render = useRender()
 
   useOnUnmount(() => {
@@ -107,7 +109,7 @@ let InternalPortalFn = forwardRefWithAs(function InternalPortalFn<
 
   let ourProps = { ref: portalRef }
 
-  return !target
+  return !target || !ready
     ? null
     : createPortal(
         <div