fix: preserve collection snapshots during hydration

[izorg]

Hello, thank you very much for your effort. I like React Aria vey much.

I first encountered the issue while integrating React Aria into a Next.js project. The Breadcrumbs component appears, disappears, and then reappears.

Summary

Intent

Preserve server-rendered collection items during hydration instead of unnecessarily removing and recreating their DOM nodes. Collection changes made by the first client effects should also be reflected correctly, including when items are removed or replaced.

Root cause

During SSR, Document.collection and Document.nextCollection reference the same collection object. When switching to client rendering, resetAfterSSR() clears the document’s child pointers before React has committed the client portal.

React’s useSyncExternalStore may read the snapshot again during this transition. Previously, that read could call updateCollection() and commit null as the first and last keys into the already-published collection. Its iterator would then return no items even though its key map and size still contained the server-rendered entries.

In Breadcrumbs, this caused React to remove the existing items and recreate them once the client collection was populated. Checking text content alone did not catch the problem because the final HTML could look unchanged.

Implementation

The fix addresses the shared collection lifecycle rather than adding a workaround to Breadcrumbs:

• Add an isHydrating state to preserve the existing snapshot and defer collection updates and notifications while the client portal is being prepared.
• Prepare a separate pending collection with the server nodes removed, so items removed by initial client effects do not remain as stale entries.
• Call finishSSR() from a layout effect in CollectionRoot after the client portal commits, allowing pending changes to be processed.
• Strengthen the Breadcrumbs SSR test to verify DOM node identity, and add collection-level coverage for initial effect updates and subsequent collection changes.

AI assistance: GitHub Copilot assisted with root-cause investigation, regression-test refinement, and drafting this description.

✅ Pull Request Checklist:

• Included link to corresponding React Spectrum GitHub Issue.
• Added/updated unit tests and storybook for this change (SSR regression tests added/updated; no new visual state requiring a Storybook change).
• Filled out test instructions.
• Updated documentation (if it already exists for this component). No public API or usage changes.
• Looked at the Accessibility Practices for this feature - Aria Practices
• I understand every change in this PR and can explain why it's there.
• If AI-assisted, I followed our AI contribution guidance and pointed my assistant at CLAUDE.md.

📝 Test Instructions:

1. Run yarn test:ssr. Without the fix Breadcrumbs.ssr.test.js and Collection.ssr.test.js fail.
2. Verify that the Breadcrumbs SSR scenario preserves the original listitem DOM nodes after hydration.
3. Verify that collection updates from the first useEffect and useLayoutEffect correctly handle clearing, replacing, and populating items. Collection size, keys, and iteration order should remain consistent after subsequent restore/reorder and clear actions.

[Copilot]

Copilot review overview

🟢 Approval recommended

No unresolved review comments were identified, and regression coverage was added.

Review effort: Lite
Findings: None

What changed in this PR

Preserves server-rendered collection snapshots during hydration and applies client updates after portal commitment.

Changes:

• Defers collection updates during hydration.
• Finalizes pending updates after client portal commit.
• Adds SSR coverage for collection changes and DOM node reuse.

File	Description
packages/​react-aria/​src/​collections/​Document.ts	Manages hydration snapshots and deferred updates.
packages/​react-aria/​src/​collections/​CollectionBuilder.tsx	Completes the SSR transition in a layout effect.
packages/​react-aria-components/​test/​Collection.ssr.test.js	Tests collection updates and iteration state.
packages/​react-aria-components/​test/​Breadcrumbs.ssr.test.js	Verifies server-rendered DOM node reuse.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[izorg]

Forgot to sign Adobe CLA