perf(ui): useAsTitle field lags on slow cpu (#12436)

jacobsfletch · web-flow · commit 18f2f899c541 · 2025-05-16T15:51:57.000-04:00
When running the Payload admin panel on a machine with a slower CPU, form state lags significantly and can become nearly unusable or even crash when interacting with the document's `useAsTitle` field. Here's an example: https://github.com/user-attachments/assets/3535fa99-1b31-4cb6-b6a8-5eb9a36b31b7 #### Why this happens The reason for this is that entire React component trees are re-rendering on every keystroke of the `useAsTitle` field, twice over. Here's a breakdown of the flow: 1. First, we dispatch form state events to the form context. Only the components that are subscribed to form state re-render when this happens (good). 2. Then, we sync the `useAsTitle` field to the document info provider, which lives outside the form. Regardless of whether its children need to be aware of the document title, all components subscribed to the document info context will re-render (there are many, including the form itself). Given how far up the rendering tree the document info provider is, its rendering footprint, and the rate of speed at which these events are dispatched, this is resource intensive. #### What is the fix The fix is to isolate the document's title into it's own context. This way only the components that are subscribed to specifically this context will re-render as the title changes. Here's the same test with the same CPU throttling, but no lag: https://github.com/user-attachments/assets/c8ced9b1-b5f0-4789-8d00-a2523d833524
diff --git a/packages/plugin-multi-tenant/src/components/WatchTenantCollection/index.tsx b/packages/plugin-multi-tenant/src/components/WatchTenantCollection/index.tsx
@@ -2,13 +2,21 @@
 
 import type { ClientCollectionConfig } from 'payload'
 
-import { useConfig, useDocumentInfo, useEffectEvent, useFormFields } from '@payloadcms/ui'
+import {
+  useConfig,
+  useDocumentInfo,
+  useDocumentTitle,
+  useEffectEvent,
+  useFormFields,
+} from '@payloadcms/ui'
 import React from 'react'
 
 import { useTenantSelection } from '../../providers/TenantSelectionProvider/index.client.js'
 
 export const WatchTenantCollection = () => {
-  const { id, collectionSlug, title } = useDocumentInfo()
+  const { id, collectionSlug } = useDocumentInfo()
+  const { title } = useDocumentTitle()
+
   const { getEntityConfig } = useConfig()
   const [useAsTitleName] = React.useState(
     () => (getEntityConfig({ collectionSlug }) as ClientCollectionConfig).admin.useAsTitle,
diff --git a/packages/plugin-seo/src/fields/MetaDescription/MetaDescriptionComponent.tsx b/packages/plugin-seo/src/fields/MetaDescription/MetaDescriptionComponent.tsx
@@ -8,6 +8,7 @@ import {
   TextareaInput,
   useConfig,
   useDocumentInfo,
+  useDocumentTitle,
   useField,
   useForm,
   useLocale,
@@ -53,6 +54,7 @@ export const MetaDescriptionComponent: React.FC<MetaDescriptionProps> = (props)
   const locale = useLocale()
   const { getData } = useForm()
   const docInfo = useDocumentInfo()
+  const { title } = useDocumentTitle()
 
   const maxLength = maxLengthFromProps || maxLengthDefault
   const minLength = minLengthFromProps || minLengthDefault
@@ -85,7 +87,7 @@ export const MetaDescriptionComponent: React.FC<MetaDescriptionProps> = (props)
         initialData: docInfo.initialData,
         initialState: reduceToSerializableFields(docInfo.initialState ?? {}),
         locale: typeof locale === 'object' ? locale?.code : locale,
-        title: docInfo.title,
+        title,
       } satisfies Omit<
         Parameters<GenerateDescription>[0],
         'collectionConfig' | 'globalConfig' | 'hasPublishedDoc' | 'req' | 'versionCount'
@@ -112,10 +114,10 @@ export const MetaDescriptionComponent: React.FC<MetaDescriptionProps> = (props)
     docInfo.hasSavePermission,
     docInfo.initialData,
     docInfo.initialState,
-    docInfo.title,
     getData,
     locale,
     setValue,
+    title,
   ])
 
   return (
diff --git a/packages/plugin-seo/src/fields/MetaImage/MetaImageComponent.tsx b/packages/plugin-seo/src/fields/MetaImage/MetaImageComponent.tsx
@@ -9,6 +9,7 @@ import {
   UploadInput,
   useConfig,
   useDocumentInfo,
+  useDocumentTitle,
   useField,
   useForm,
   useLocale,
@@ -56,6 +57,8 @@ export const MetaImageComponent: React.FC<MetaImageProps> = (props) => {
   const { getData } = useForm()
   const docInfo = useDocumentInfo()
 
+  const { title } = useDocumentTitle()
+
   const regenerateImage = useCallback(async () => {
     if (!hasGenerateImageFn) {
       return
@@ -75,7 +78,7 @@ export const MetaImageComponent: React.FC<MetaImageProps> = (props) => {
         initialData: docInfo.initialData,
         initialState: reduceToSerializableFields(docInfo.initialState ?? {}),
         locale: typeof locale === 'object' ? locale?.code : locale,
-        title: docInfo.title,
+        title,
       } satisfies Omit<
         Parameters<GenerateImage>[0],
         'collectionConfig' | 'globalConfig' | 'hasPublishedDoc' | 'req' | 'versionCount'
@@ -102,10 +105,10 @@ export const MetaImageComponent: React.FC<MetaImageProps> = (props) => {
     docInfo.hasSavePermission,
     docInfo.initialData,
     docInfo.initialState,
-    docInfo.title,
     getData,
     locale,
     setValue,
+    title,
   ])
 
   const hasImage = Boolean(value)
diff --git a/packages/plugin-seo/src/fields/MetaTitle/MetaTitleComponent.tsx b/packages/plugin-seo/src/fields/MetaTitle/MetaTitleComponent.tsx
@@ -8,6 +8,7 @@ import {
   TextInput,
   useConfig,
   useDocumentInfo,
+  useDocumentTitle,
   useField,
   useForm,
   useLocale,
@@ -57,6 +58,7 @@ export const MetaTitleComponent: React.FC<MetaTitleProps> = (props) => {
   const locale = useLocale()
   const { getData } = useForm()
   const docInfo = useDocumentInfo()
+  const { title } = useDocumentTitle()
 
   const minLength = minLengthFromProps || minLengthDefault
   const maxLength = maxLengthFromProps || maxLengthDefault
@@ -80,7 +82,7 @@ export const MetaTitleComponent: React.FC<MetaTitleProps> = (props) => {
         initialData: docInfo.initialData,
         initialState: reduceToSerializableFields(docInfo.initialState ?? {}),
         locale: typeof locale === 'object' ? locale?.code : locale,
-        title: docInfo.title,
+        title,
       } satisfies Omit<
         Parameters<GenerateTitle>[0],
         'collectionConfig' | 'globalConfig' | 'hasPublishedDoc' | 'req' | 'versionCount'
@@ -107,10 +109,10 @@ export const MetaTitleComponent: React.FC<MetaTitleProps> = (props) => {
     docInfo.hasSavePermission,
     docInfo.initialData,
     docInfo.initialState,
-    docInfo.title,
     getData,
     locale,
     setValue,
+    title,
   ])
 
   return (
diff --git a/packages/plugin-seo/src/fields/Preview/PreviewComponent.tsx b/packages/plugin-seo/src/fields/Preview/PreviewComponent.tsx
@@ -6,6 +6,7 @@ import {
   useAllFormFields,
   useConfig,
   useDocumentInfo,
+  useDocumentTitle,
   useForm,
   useLocale,
   useTranslation,
@@ -42,6 +43,7 @@ export const PreviewComponent: React.FC<PreviewProps> = (props) => {
   const [fields] = useAllFormFields()
   const { getData } = useForm()
   const docInfo = useDocumentInfo()
+  const { title } = useDocumentTitle()
 
   const descriptionPath = descriptionPathFromContext || 'meta.description'
   const titlePath = titlePathFromContext || 'meta.title'
@@ -69,7 +71,7 @@ export const PreviewComponent: React.FC<PreviewProps> = (props) => {
           initialData: docInfo.initialData,
           initialState: reduceToSerializableFields(docInfo.initialState ?? {}),
           locale: typeof locale === 'object' ? locale?.code : locale,
-          title: docInfo.title,
+          title,
         } satisfies Omit<
           Parameters<GenerateURL>[0],
           'collectionConfig' | 'globalConfig' | 'hasPublishedDoc' | 'req' | 'versionCount'
@@ -89,7 +91,7 @@ export const PreviewComponent: React.FC<PreviewProps> = (props) => {
     if (hasGenerateURLFn && !href) {
       void getHref()
     }
-  }, [fields, href, locale, docInfo, hasGenerateURLFn, getData, serverURL, api])
+  }, [fields, href, locale, docInfo, hasGenerateURLFn, getData, serverURL, api, title])
 
   return (
     <div
diff --git a/packages/ui/src/elements/Autosave/index.tsx b/packages/ui/src/elements/Autosave/index.tsx
@@ -44,6 +44,7 @@ export const Autosave: React.FC<Props> = ({ id, collection, global: globalDoc })
       serverURL,
     },
   } = useConfig()
+
   const {
     docConfig,
     incrementVersionCount,
diff --git a/packages/ui/src/elements/DeleteDocument/index.tsx b/packages/ui/src/elements/DeleteDocument/index.tsx
@@ -12,7 +12,7 @@ import type { DocumentDrawerContextType } from '../DocumentDrawer/Provider.js'
 
 import { useForm } from '../../forms/Form/context.js'
 import { useConfig } from '../../providers/Config/index.js'
-import { useDocumentInfo } from '../../providers/DocumentInfo/index.js'
+import { useDocumentTitle } from '../../providers/DocumentTitle/index.js'
 import { useRouteTransition } from '../../providers/RouteTransition/index.js'
 import { useTranslation } from '../../providers/Translation/index.js'
 import { requests } from '../../utilities/api.js'
@@ -56,7 +56,7 @@ export const DeleteDocument: React.FC<Props> = (props) => {
   const { setModified } = useForm()
   const router = useRouter()
   const { i18n, t } = useTranslation()
-  const { title } = useDocumentInfo()
+  const { title } = useDocumentTitle()
   const { startRouteTransition } = useRouteTransition()
   const { openModal } = useModal()
 
diff --git a/packages/ui/src/elements/DocumentDrawer/DrawerHeader/index.tsx b/packages/ui/src/elements/DocumentDrawer/DrawerHeader/index.tsx
@@ -5,6 +5,7 @@ import { useModal } from '../../../elements/Modal/index.js'
 import { RenderTitle } from '../../../elements/RenderTitle/index.js'
 import { XIcon } from '../../../icons/X/index.js'
 import { useDocumentInfo } from '../../../providers/DocumentInfo/index.js'
+import { useDocumentTitle } from '../../../providers/DocumentTitle/index.js'
 import { useTranslation } from '../../../providers/Translation/index.js'
 import { IDLabel } from '../../IDLabel/index.js'
 import { documentDrawerBaseClass } from '../index.js'
@@ -37,6 +38,7 @@ export const DocumentDrawerHeader: React.FC<{
 }
 
 const DocumentTitle: React.FC = () => {
-  const { id, title } = useDocumentInfo()
+  const { id } = useDocumentInfo()
+  const { title } = useDocumentTitle()
   return id && id !== title ? <IDLabel id={id.toString()} /> : null
 }
diff --git a/packages/ui/src/elements/PublishButton/ScheduleDrawer/index.tsx b/packages/ui/src/elements/PublishButton/ScheduleDrawer/index.tsx
@@ -17,6 +17,7 @@ import { FieldLabel } from '../../../fields/FieldLabel/index.js'
 import { Radio } from '../../../fields/RadioGroup/Radio/index.js'
 import { useConfig } from '../../../providers/Config/index.js'
 import { useDocumentInfo } from '../../../providers/DocumentInfo/index.js'
+import { useDocumentTitle } from '../../../providers/DocumentTitle/index.js'
 import { useServerFunctions } from '../../../providers/ServerFunctions/index.js'
 import { useTranslation } from '../../../providers/Translation/index.js'
 import { requests } from '../../../utilities/api.js'
@@ -59,7 +60,8 @@ export const ScheduleDrawer: React.FC<Props> = ({ slug, defaultType, schedulePub
       serverURL,
     },
   } = useConfig()
-  const { id, collectionSlug, globalSlug, title } = useDocumentInfo()
+  const { id, collectionSlug, globalSlug } = useDocumentInfo()
+  const { title } = useDocumentTitle()
   const { i18n, t } = useTranslation()
   const { schedulePublish } = useServerFunctions()
   const [type, setType] = React.useState<PublishType>(defaultType || 'publish')
diff --git a/packages/ui/src/elements/RenderTitle/index.tsx b/packages/ui/src/elements/RenderTitle/index.tsx
@@ -2,6 +2,7 @@
 import React, { Fragment } from 'react'
 
 import { useDocumentInfo } from '../../providers/DocumentInfo/index.js'
+import { useDocumentTitle } from '../../providers/DocumentTitle/index.js'
 import { IDLabel } from '../IDLabel/index.js'
 import './index.scss'
 
@@ -18,7 +19,8 @@ export type RenderTitleProps = {
 export const RenderTitle: React.FC<RenderTitleProps> = (props) => {
   const { className, element = 'h1', fallback, title: titleFromProps } = props
 
-  const { id, isInitializing, title: titleFromContext } = useDocumentInfo()
+  const { id, isInitializing } = useDocumentInfo()
+  const { title: titleFromContext } = useDocumentTitle()
 
   const title = titleFromProps || titleFromContext || fallback
 
diff --git a/packages/ui/src/elements/SaveDraftButton/index.tsx b/packages/ui/src/elements/SaveDraftButton/index.tsx
@@ -23,6 +23,7 @@ export function SaveDraftButton(props: SaveDraftButtonClientProps) {
       serverURL,
     },
   } = useConfig()
+
   const { id, collectionSlug, globalSlug, setUnpublishedVersionCount, uploadStatus } =
     useDocumentInfo()
 
diff --git a/packages/ui/src/elements/Status/index.tsx b/packages/ui/src/elements/Status/index.tsx
@@ -28,13 +28,16 @@ export const Status: React.FC = () => {
     setUnpublishedVersionCount,
     unpublishedVersionCount,
   } = useDocumentInfo()
+
   const { toggleModal } = useModal()
+
   const {
     config: {
       routes: { api },
       serverURL,
     },
   } = useConfig()
+
   const { reset: resetForm } = useForm()
   const { code: locale } = useLocale()
   const { i18n, t } = useTranslation()
diff --git a/packages/ui/src/exports/client/index.ts b/packages/ui/src/exports/client/index.ts
@@ -277,6 +277,7 @@ export {
 export { ConfigProvider, useConfig } from '../../providers/Config/index.js'
 export { DocumentEventsProvider, useDocumentEvents } from '../../providers/DocumentEvents/index.js'
 export { DocumentInfoProvider, useDocumentInfo } from '../../providers/DocumentInfo/index.js'
+export { useDocumentTitle } from '../../providers/DocumentTitle/index.js'
 export type { DocumentInfoContext, DocumentInfoProps } from '../../providers/DocumentInfo/index.js'
 
 export { EditDepthProvider, useEditDepth } from '../../providers/EditDepth/index.js'
diff --git a/packages/ui/src/providers/DocumentInfo/index.tsx b/packages/ui/src/providers/DocumentInfo/index.tsx
@@ -4,16 +4,16 @@ import type { ClientUser, DocumentPreferences, SanitizedDocumentPermissions } fr
 import * as qs from 'qs-esm'
 import React, { createContext, use, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 
-import type { DocumentInfoContext, DocumentInfoProps } from './types.js'
-
 import { useAuth } from '../../providers/Auth/index.js'
 import { requests } from '../../utilities/api.js'
 import { formatDocTitle } from '../../utilities/formatDocTitle/index.js'
 import { useConfig } from '../Config/index.js'
+import { DocumentTitleProvider } from '../DocumentTitle/index.js'
 import { useLocale, useLocaleLoading } from '../Locale/index.js'
 import { usePreferences } from '../Preferences/index.js'
 import { useTranslation } from '../Translation/index.js'
 import { UploadEditsProvider, useUploadEdits } from '../UploadEdits/index.js'
+import { type DocumentInfoContext, type DocumentInfoProps } from './types.js'
 import { useGetDocPermissions } from './useGetDocPermissions.js'
 
 const Context = createContext({} as DocumentInfoContext)
@@ -75,7 +75,11 @@ const DocumentInfo: React.FC<
 
   const { uploadEdits } = useUploadEdits()
 
-  const [documentTitle, setDocumentTitle] = useState(() =>
+  /**
+   * @deprecated This state will be removed in v4.
+   * This is for performance reasons. Use the `DocumentTitleContext` instead.
+   */
+  const [title, setDocumentTitle] = useState(() =>
     formatDocTitle({
       collectionConfig,
       data: { ...(initialData || {}), id },
@@ -272,6 +276,10 @@ const DocumentInfo: React.FC<
     [],
   )
 
+  /**
+   * @todo: Remove this in v4
+   * Users should use the `DocumentTitleContext` instead.
+   */
   useEffect(() => {
     setDocumentTitle(
       formatDocTitle({
@@ -343,7 +351,7 @@ const DocumentInfo: React.FC<
     setMostRecentVersionIsAutosaved,
     setUnpublishedVersionCount,
     setUploadStatus: updateUploadStatus,
-    title: documentTitle,
+    title,
     unlockDocument,
     unpublishedVersionCount,
     updateDocumentEditor,
@@ -352,7 +360,11 @@ const DocumentInfo: React.FC<
     versionCount,
   }
 
-  return <Context value={value}>{children}</Context>
+  return (
+    <Context value={value}>
+      <DocumentTitleProvider>{children}</DocumentTitleProvider>
+    </Context>
+  )
 }
 
 export const DocumentInfoProvider: React.FC<
diff --git a/packages/ui/src/providers/DocumentInfo/types.ts b/packages/ui/src/providers/DocumentInfo/types.ts
@@ -11,7 +11,8 @@ import type {
   SanitizedGlobalConfig,
   TypedUser,
 } from 'payload'
-import type React from 'react'
+
+import React from 'react'
 
 export type DocumentInfoProps = {
   readonly action?: string
@@ -60,12 +61,31 @@ export type DocumentInfoContext = {
     fieldPreferences: { [key: string]: unknown } & Partial<InsideFieldsPreferences>,
   ) => void
   setDocumentIsLocked?: React.Dispatch<React.SetStateAction<boolean>>
-  setDocumentTitle: (title: string) => void
+  /**
+   *
+   * @deprecated This property is deprecated and will be removed in v4.
+   * This is for performance reasons. Use the `DocumentTitleContext` instead.
+   * @example
+   * ```tsx
+   * import { useDocumentTitle } from '@payloadcms/ui'
+   * const { setDocumentTitle }  = useDocumentTitle()
+   * ```
+   */
+  setDocumentTitle: React.Dispatch<React.SetStateAction<string>>
   setHasPublishedDoc: React.Dispatch<React.SetStateAction<boolean>>
   setLastUpdateTime: React.Dispatch<React.SetStateAction<number>>
   setMostRecentVersionIsAutosaved: React.Dispatch<React.SetStateAction<boolean>>
   setUnpublishedVersionCount: React.Dispatch<React.SetStateAction<number>>
   setUploadStatus?: (status: 'failed' | 'idle' | 'uploading') => void
+  /**
+   * @deprecated This property is deprecated and will be removed in v4.
+   * This is for performance reasons. Use the `DocumentTitleContext` instead.
+   * @example
+   * ```tsx
+   * import { useDocumentTitle } from '@payloadcms/ui'
+   * const { title }  = useDocumentTitle()
+   * ```
+   */
   title: string
   unlockDocument: (docID: number | string, slug: string) => Promise<void>
   unpublishedVersionCount: number
@@ -74,3 +94,5 @@ export type DocumentInfoContext = {
   uploadStatus?: 'failed' | 'idle' | 'uploading'
   versionCount: number
 } & DocumentInfoProps
+
+export const DocumentTitleContext = React.createContext<string>('')
diff --git a/packages/ui/src/providers/DocumentTitle/context.ts b/packages/ui/src/providers/DocumentTitle/context.ts
diff --git a/packages/ui/src/providers/DocumentTitle/index.tsx b/packages/ui/src/providers/DocumentTitle/index.tsx
diff --git a/packages/ui/src/utilities/formatDocTitle/index.ts b/packages/ui/src/utilities/formatDocTitle/index.ts
diff --git a/packages/ui/src/views/Edit/Auth/index.tsx b/packages/ui/src/views/Edit/Auth/index.tsx
diff --git a/packages/ui/src/views/Edit/SetDocumentStepNav/index.tsx b/packages/ui/src/views/Edit/SetDocumentStepNav/index.tsx
diff --git a/packages/ui/src/views/Edit/SetDocumentTitle/index.tsx b/packages/ui/src/views/Edit/SetDocumentTitle/index.tsx
diff --git a/test/form-state/e2e.spec.ts b/test/form-state/e2e.spec.ts
