perf: prevent form rerenders

[GermanJablo]

Fixes #14213

Summary

Fixes unnecessary re-renders of all Form children when any field changes.
The issue was that the Form component passed a memoized array [formState, dispatchFields] to the context provider, which changed on every field update, causing all children to re-render regardless of whether they used useFormFields or not.

This PR replaces use-context-selector with React’s native useSyncExternalStore API and implements a stable store pattern that prevents the Provider’s value from changing, ensuring only components using useFormFields with changed selector values will re-render.

Root Cause Analysis

The issue reported in #14213 was not that useFormFields was causing unnecessary re-renders. The hook itself worked correctly with use-context-selector, re-rendering only when the selected field changed.

The real problem was that the entire Form component tree re-rendered on any field change because:

// Before
const fieldsReducer = useReducer(fieldReducer, initialState)
const [formState, dispatchFields] = fieldsReducer

// This array is recreated on every render when formState changes
<FormFieldsContext.Provider value={fieldsReducer}>
  {children}
</FormFieldsContext.Provider>

When typing in the title field, formState changes → new array [formState, dispatchFields] → Provider's value changes → all children re-render (not just components using useFormFields).

Why useMemo Doesn't Solve It

// This doesn't work
const fieldsContextValue = useMemo(() => [formState, dispatchFields], [formState, dispatchFields])

The memoized value still changes whenever formState changes (which happens on every keystroke), so the Provider still receives a new value and re-renders all children.

Solution: Stable Store Pattern

The fix uses useSyncExternalStore with a completely stable store object:

const formFieldsStore = React.useMemo<FormFieldsStore>(() => ({
  getState: () => [formStateRef.current, dispatchFieldsRef.current],
  subscribe: (listener) => {
    listenersRef.current.add(listener)
    return () => listenersRef.current.delete(listener)
  }
}), []) // ← No dependencies! Store identity never changes

Now:

1. The store object passed to the Provider never changes identity
2. State changes are tracked via refs and manual notifications
3. Only components calling useFormFields with selectors that return different values will re-render
4. All other children are unaffected by field changes

Changes

• Removed dependency: use-context-selector
• Replaced with: useSyncExternalStore. React's official API for external state synchronization
• Created stable store: Form fields store is memoized with no dependencies
• Added test: E2E test verifies typing in one field doesn’t trigger re-renders of components using useFormFields to watch other fields

Why useSyncExternalStore Is Necessary

This isn’t just a modernization. it’s the only way to achieve:

• A Provider value that never changes (stable store object)
• Selective subscriptions where components decide when to re-render
• No re-renders of unrelated children when any field changes

Benefits

1. Performance: Prevents unnecessary re-renders across the entire Form tree
2. Native React API: Designed for this exact use case since React 18
3. Concurrent React safe: Handles tearing, interrupted renders, and concurrent transitions
4. Future-proof: Official API with guaranteed support for RSC and future features
5. Smaller bundle: Removes external dependency
6. Industry standard: Same pattern used by Redux, Zustand, and Jotai

[github-actions]

📦 esbuild Bundle Analysis for payload

This analysis was generated by esbuild-bundle-analyzer. 🤖

Meta File	Out File	Size (raw)	Note
packages/next/meta_index.json	esbuild/index.js	755.32 KB	🆕 Added
packages/payload/meta_index.json	esbuild/index.js	1.22 MB	🆕 Added
packages/payload/meta_shared.json	esbuild/exports/shared.js	162.59 KB	🆕 Added
packages/richtext-lexical/meta_client.json	esbuild/exports/client_optimized/index.js	279.48 KB	🆕 Added
packages/ui/meta_client.json	esbuild/exports/client_optimized/index.js	1.14 MB	🆕 Added
packages/ui/meta_shared.json	esbuild/exports/shared_optimized/index.js	14.39 KB	🆕 Added

Largest paths

These visualization shows top 20 largest paths in the bundle.

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████████████ }}}$ 80.2%, 601.84 KB
dist/views/Version	${{\color{Goldenrod}{ █▋ }}}$ 6.6%, 49.56 KB
dist/views/Document	${{\color{Goldenrod}{ ▌ }}}$ 2.0%, 15.23 KB
dist/views/List	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 10.46 KB
dist/views/Root	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 8.61 KB
dist/views/API	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 5.98 KB
dist/views/Versions	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 5.96 KB
dist/elements/Nav	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 5.53 KB
dist/views/Account	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 5.32 KB
dist/elements/DocumentHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 4.81 KB
dist/views/Login	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 4.39 KB
dist/views/Dashboard	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 3.69 KB
dist/layouts/Root	${{\color{Goldenrod}{ }}}$ 0.4%, 3.11 KB
dist/views/ForgotPassword	${{\color{Goldenrod}{ }}}$ 0.4%, 3.09 KB
dist/templates/Default	${{\color{Goldenrod}{ }}}$ 0.4%, 2.83 KB
dist/views/CreateFirstUser	${{\color{Goldenrod}{ }}}$ 0.4%, 2.76 KB
dist/views/BrowseByFolder	${{\color{Goldenrod}{ }}}$ 0.3%, 2.60 KB
dist/views/CollectionFolders	${{\color{Goldenrod}{ }}}$ 0.3%, 2.46 KB
dist/views/ResetPassword	${{\color{Goldenrod}{ }}}$ 0.3%, 2.41 KB
dist/views/Logout	${{\color{Goldenrod}{ }}}$ 0.3%, 1.91 KB
(other)	${{\color{Goldenrod}{ ████▉ }}}$ 19.8%, 148.80 KB

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ █████████████████▎ }}}$ 69.2%, 841.06 KB
dist/fields/hooks	${{\color{Goldenrod}{ ▊ }}}$ 3.4%, 41.94 KB
dist/collections/operations	${{\color{Goldenrod}{ ▊ }}}$ 3.0%, 37.00 KB
dist/auth/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.30 KB
dist/queues/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 12.04 KB
dist/globals/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 11.90 KB
dist/fields/config	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 11.57 KB
dist/utilities/configToJSONSchema.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 11.54 KB
dist/fields/validations.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 10.21 KB
dist/bin/generateImportMap	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.31 KB
dist/collections/config	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.88 KB
dist/database/migrations	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.79 KB
dist/uploads/fetchAPI-multipart	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.74 KB
dist/index.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.51 KB
dist/collections/endpoints	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.40 KB
dist/config/orderable	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 6.27 KB
dist/auth/strategies	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 5.50 KB
dist/config/sanitize.js	${{\color{Goldenrod}{ }}}$ 0.4%, 5.44 KB
dist/auth/endpoints	${{\color{Goldenrod}{ }}}$ 0.4%, 5.41 KB
dist/utilities/telemetry	${{\color{Goldenrod}{ }}}$ 0.4%, 5.31 KB
(other)	${{\color{Goldenrod}{ ███████▋ }}}$ 30.8%, 374.73 KB

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ███████████████████▉ }}}$ 79.7%, 126.93 KB
dist/fields/validations.js	${{\color{Goldenrod}{ █▌ }}}$ 6.4%, 10.21 KB
dist/fields/baseFields	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 2.79 KB
dist/utilities/deepCopyObject.js	${{\color{Goldenrod}{ ▍ }}}$ 1.6%, 2.48 KB
dist/auth/cookies.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 1.55 KB
dist/utilities/flattenTopLevelFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 1.42 KB
dist/fields/config	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 1.28 KB
dist/utilities/flattenAllFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 943 B
dist/folders/utils	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 916 B
dist/utilities/unflatten.js	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 779 B
dist/utilities/sanitizeUserDataForEmail.js	${{\color{Goldenrod}{ }}}$ 0.4%, 713 B
dist/utilities/getFieldPermissions.js	${{\color{Goldenrod}{ }}}$ 0.4%, 651 B
dist/collections/config	${{\color{Goldenrod}{ }}}$ 0.4%, 570 B
dist/bin/generateImportMap	${{\color{Goldenrod}{ }}}$ 0.4%, 561 B
dist/auth/sessions.js	${{\color{Goldenrod}{ }}}$ 0.3%, 545 B
dist/utilities/getSafeRedirect.js	${{\color{Goldenrod}{ }}}$ 0.3%, 423 B
dist/utilities/deepMerge.js	${{\color{Goldenrod}{ }}}$ 0.3%, 413 B
dist/utilities/formatLabels.js	${{\color{Goldenrod}{ }}}$ 0.2%, 380 B
dist/utilities/appendUploadSelectFields.js	${{\color{Goldenrod}{ }}}$ 0.2%, 360 B
dist/utilities/transformColumnPreferences.js	${{\color{Goldenrod}{ }}}$ 0.2%, 348 B
(other)	${{\color{Goldenrod}{ █████ }}}$ 20.3%, 32.37 KB

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Path	Size
dist/features/blocks	${{\color{Goldenrod}{ ███ }}}$ 12.4%, 34.24 KB
dist/lexical/plugins	${{\color{Goldenrod}{ ██▊ }}}$ 11.4%, 31.61 KB
dist/lexical/ui	${{\color{Goldenrod}{ ██▏ }}}$ 8.8%, 24.23 KB
dist/features/experimental_table	${{\color{Goldenrod}{ ██▏ }}}$ 8.6%, 23.70 KB
dist/packages/@lexical	${{\color{Goldenrod}{ █▋ }}}$ 6.9%, 18.99 KB
dist/features/link	${{\color{Goldenrod}{ █▋ }}}$ 6.5%, 18.03 KB
dist/features/toolbars	${{\color{Goldenrod}{ █▌ }}}$ 6.4%, 17.75 KB
dist/features/upload	${{\color{Goldenrod}{ █▏ }}}$ 4.9%, 13.51 KB
dist/features/textState	${{\color{Goldenrod}{ █ }}}$ 4.0%, 11.08 KB
dist/features/relationship	${{\color{Goldenrod}{ ▊ }}}$ 3.2%, 8.72 KB
dist/lexical/utils	${{\color{Goldenrod}{ ▋ }}}$ 2.9%, 8.08 KB
dist/features/debug	${{\color{Goldenrod}{ ▋ }}}$ 2.7%, 7.39 KB
dist/utilities/fieldsDrawer	${{\color{Goldenrod}{ ▋ }}}$ 2.6%, 7.12 KB
dist/features/converters	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 7.04 KB
dist/lexical/config	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 5.10 KB
dist/features/lists	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 5.00 KB
dist/lexical/theme	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 4.01 KB
dist/features/format	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 3.46 KB
dist/lexical/LexicalEditor.js	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 3.17 KB
dist/features/indent	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 2.50 KB
(other)	${{\color{Goldenrod}{ █████████████████████▉ }}}$ 87.6%, 242.06 KB

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████▌ }}}$ 50.0%, 567.49 KB
dist/elements/FolderView	${{\color{Goldenrod}{ ▋ }}}$ 2.6%, 29.14 KB
dist/elements/BulkUpload	${{\color{Goldenrod}{ ▌ }}}$ 2.4%, 26.93 KB
dist/elements/WhereBuilder	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 16.25 KB
dist/views/Edit	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 15.91 KB
dist/forms/Form	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 15.76 KB
dist/fields/Relationship	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 15.40 KB
dist/elements/Table	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.29 KB
dist/fields/Blocks	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 12.87 KB
dist/fields/Upload	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 11.49 KB
dist/elements/PublishButton	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 8.73 KB
dist/providers/Folders	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.48 KB
dist/elements/LivePreview	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.38 KB
dist/elements/QueryPresets	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.36 KB
dist/elements/ListHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.83 KB
dist/elements/HTMLDiff	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.81 KB
dist/fields/Array	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.56 KB
dist/views/CollectionFolder	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.36 KB
dist/views/List	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.95 KB
dist/elements/ReactSelect	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.91 KB
(other)	${{\color{Goldenrod}{ ████████████▌ }}}$ 50.0%, 566.53 KB

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Path	Size
dist/graphics/Logo	${{\color{Goldenrod}{ █████▋ }}}$ 22.6%, 3.12 KB
../../node_modules	${{\color{Goldenrod}{ ████▊ }}}$ 19.2%, 2.65 KB
dist/graphics/Icon	${{\color{Goldenrod}{ ██▊ }}}$ 11.0%, 1.52 KB
dist/utilities/formatDocTitle	${{\color{Goldenrod}{ ██▍ }}}$ 9.6%, 1.32 KB
dist/providers/TableColumns	${{\color{Goldenrod}{ █▌ }}}$ 6.2%, 862 B
dist/utilities/groupNavItems.js	${{\color{Goldenrod}{ █▍ }}}$ 5.9%, 814 B
dist/utilities/api.js	${{\color{Goldenrod}{ █▍ }}}$ 5.5%, 756 B
dist/elements/Translation	${{\color{Goldenrod}{ ▉ }}}$ 3.6%, 493 B
dist/utilities/handleTakeOver.js	${{\color{Goldenrod}{ ▊ }}}$ 3.2%, 440 B
dist/elements/withMergedProps	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 339 B
dist/elements/WithServerSideProps	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 232 B
dist/utilities/handleGoBack.js	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 168 B
dist/fields/mergeFieldStyles.js	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 159 B
dist/forms/Form	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 147 B
dist/utilities/abortAndIgnore.js	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 146 B
dist/utilities/hasSavePermission.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 136 B
dist/utilities/handleBackToDashboard.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 129 B
dist/utilities/findLocaleFromCode.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 84 B
dist/utilities/sanitizeID.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 77 B
dist/utilities/isEditing.js	${{\color{Goldenrod}{ }}}$ 0.4%, 59 B
(other)	${{\color{Goldenrod}{ ███████████████████▎ }}}$ 77.4%, 10.68 KB

Details

Next to the size is how much the size has increased or decreased compared with the base branch of this PR.

• ‼️: Size increased by 20% or more. Special attention should be given to this.
• ⚠️: Size increased in acceptable range (lower than 20%).
• ✅: No change or even downsized.
• 🗑️: The out file is deleted: not found in base branch.
• 🆕: The out file is newly found: will be added to base branch.

[philipp-tailor]

It's a shame that this PR is closed, this change has big system improvement potential. Unnecessary component re-rendering (even if not executing the 2nd React render phase) in large document continues to be a UI performance bottleneck in our Payload based CMS on CPU-limited clients.

[GermanJablo]

Yes, it's something I'd like to address at some point.
I canceled it because it was taking too long, and I don't know if it's the most critical bottleneck performance-wise. It's better to evaluate the latency cases individually to determine this.

The remaining solution to explore is whether it's possible to make formState stable (not change to a new object), and to update all our hooks that depend on formState so they can listen for granular subscriptions.

Something like this is what this PR attempted to explore with useFormFields, but I ran into a lot of issues along the way. Infinite loops, among other things.

Also, I don't know if making formState stable would break code that doesn't use our React hooks, so I'm not sure yet if this solution would be viable.

If there are any payload configurations that are experiencing performance issues on low-end devices, please send us a reproducible and we will investigate the best course of action to resolve it.