refactor(ui): live preview iframe loader by jacobsfletch · Pull Request #16004 · payloadcms/payload

jacobsfletch · 2026-03-19T16:56:52Z

Continuation of #15999.

Without optimistically loading the live preview window, the initial loading state is left unhandled when toggling into live preview for the first time. This causes users to see blank content until the iframe has loaded, without indication that something is happening.

Now, we display a loading indicator while the iframe request is in flight, that notably:

Only shows if the load takes longer than x ms.
If shown, is forced to remain in place for at least x ms to avoid flickering, even if the request finishes before then.

Before:

Screen.Recording.2026-03-19.at.1.23.10.PM.mp4

After:

Screen.Recording.2026-03-19.at.4.36.05.PM.mp4

The ShimmerEffect component now accepts arbitrary HTML attributes and supports a new transparent prop

To see the specific tasks where the Asana app for GitHub is being used, see below:
- https://app.asana.com/0/0/1213727956884086

github-actions · 2026-03-19T17:08:00Z

📦 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	984.61 KB	✅ No change
packages/payload/meta_index.json	esbuild/index.js	1.34 MB	✅ No change
packages/payload/meta_shared.json	esbuild/exports/shared.js	190.93 KB	✅ No change
packages/richtext-lexical/meta_client.json	esbuild/exports/client_optimized/index.js	280.56 KB	✅ No change
packages/ui/meta_client.json	esbuild/exports/client_optimized/index.js	1.18 MB	⚠️ +65 B (+0.0%)
packages/ui/meta_shared.json	esbuild/exports/shared_optimized/index.js	16.32 KB	✅ No change

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}{ ████████████████████▋ }}}$ 82.5%, 808.32 KB
dist/views/Version	${{\color{Goldenrod}{ █▎ }}}$ 5.3%, 51.49 KB
dist/views/Dashboard	${{\color{Goldenrod}{ ▌ }}}$ 2.2%, 21.37 KB
dist/views/Document	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 16.59 KB
dist/views/List	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 11.38 KB
dist/views/Root	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 9.03 KB
dist/views/Versions	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.17 KB
dist/views/API	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.08 KB
dist/elements/Nav	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 5.96 KB
dist/views/Account	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 5.55 KB
dist/elements/DocumentHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 4.81 KB
dist/views/Login	${{\color{Goldenrod}{ }}}$ 0.4%, 4.40 KB
dist/views/ForgotPassword	${{\color{Goldenrod}{ }}}$ 0.3%, 3.09 KB
dist/layouts/Root	${{\color{Goldenrod}{ }}}$ 0.3%, 2.91 KB
dist/views/CreateFirstUser	${{\color{Goldenrod}{ }}}$ 0.3%, 2.81 KB
dist/templates/Default	${{\color{Goldenrod}{ }}}$ 0.3%, 2.64 KB
dist/views/BrowseByFolder	${{\color{Goldenrod}{ }}}$ 0.3%, 2.61 KB
dist/views/CollectionFolders	${{\color{Goldenrod}{ }}}$ 0.2%, 2.44 KB
dist/views/ResetPassword	${{\color{Goldenrod}{ }}}$ 0.2%, 2.40 KB
dist/views/Logout	${{\color{Goldenrod}{ }}}$ 0.2%, 1.94 KB
(other)	${{\color{Goldenrod}{ ████▍ }}}$ 17.5%, 171.61 KB

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

Path	Size
../../node_modules	${{\color{Goldenrod}{ █████████████████ }}}$ 68.0%, 908.21 KB
dist/fields/hooks	${{\color{Goldenrod}{ ▊ }}}$ 3.3%, 43.59 KB
dist/collections/operations	${{\color{Goldenrod}{ ▊ }}}$ 3.0%, 39.91 KB
dist/versions/migrations	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 18.50 KB
dist/auth/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 15.63 KB
dist/globals/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 13.17 KB
dist/utilities/configToJSONSchema.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 13.13 KB
dist/fields/config	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 12.90 KB
dist/queues/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 12.80 KB
dist/fields/validations.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 10.54 KB
dist/bin/generateImportMap	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.87 KB
dist/config/orderable	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 8.65 KB
dist/collections/config	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 8.35 KB
dist/index.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.69 KB
dist/uploads/fetchAPI-multipart	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.67 KB
dist/database/migrations	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.54 KB
dist/collections/endpoints	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 6.23 KB
dist/config/sanitize.js	${{\color{Goldenrod}{ }}}$ 0.4%, 5.80 KB
dist/auth/strategies	${{\color{Goldenrod}{ }}}$ 0.4%, 5.50 KB
dist/queues/config	${{\color{Goldenrod}{ }}}$ 0.4%, 5.34 KB
(other)	${{\color{Goldenrod}{ ████████ }}}$ 32.0%, 428.07 KB

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

Path	Size
../../node_modules	${{\color{Goldenrod}{ ███████████████████▊ }}}$ 79.3%, 148.51 KB
dist/fields/validations.js	${{\color{Goldenrod}{ █▍ }}}$ 5.6%, 10.54 KB
dist/config/orderable	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 3.13 KB
dist/fields/baseFields	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 2.79 KB
dist/utilities/deepCopyObject.js	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 2.54 KB
dist/auth/cookies.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 1.55 KB
dist/utilities/flattenTopLevelFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 1.42 KB
dist/fields/config	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 1.28 KB
dist/utilities/getVersionsConfig.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 1.04 KB
dist/utilities/flattenAllFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 943 B
dist/folders/utils	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 916 B
dist/utilities/unflatten.js	${{\color{Goldenrod}{ }}}$ 0.4%, 779 B
dist/utilities/sanitizeUserDataForEmail.js	${{\color{Goldenrod}{ }}}$ 0.4%, 713 B
dist/utilities/getFieldPermissions.js	${{\color{Goldenrod}{ }}}$ 0.3%, 651 B
dist/collections/config	${{\color{Goldenrod}{ }}}$ 0.3%, 570 B
dist/bin/generateImportMap	${{\color{Goldenrod}{ }}}$ 0.3%, 561 B
dist/auth/sessions.js	${{\color{Goldenrod}{ }}}$ 0.3%, 525 B
dist/fields/getFieldPaths.js	${{\color{Goldenrod}{ }}}$ 0.3%, 485 B
dist/errors/APIError.js	${{\color{Goldenrod}{ }}}$ 0.2%, 438 B
dist/utilities/getSafeRedirect.js	${{\color{Goldenrod}{ }}}$ 0.2%, 423 B
(other)	${{\color{Goldenrod}{ █████▏ }}}$ 20.7%, 38.75 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.8%, 35.38 KB
dist/lexical/plugins	${{\color{Goldenrod}{ ██▉ }}}$ 11.5%, 32.00 KB
dist/lexical/ui	${{\color{Goldenrod}{ ██▏ }}}$ 8.8%, 24.36 KB
dist/features/experimental_table	${{\color{Goldenrod}{ ██▏ }}}$ 8.5%, 23.70 KB
dist/packages/@lexical	${{\color{Goldenrod}{ █▋ }}}$ 6.8%, 18.99 KB
dist/features/link	${{\color{Goldenrod}{ █▋ }}}$ 6.6%, 18.24 KB
dist/features/toolbars	${{\color{Goldenrod}{ █▍ }}}$ 5.8%, 16.08 KB
dist/features/upload	${{\color{Goldenrod}{ █▎ }}}$ 5.0%, 13.77 KB
dist/features/textState	${{\color{Goldenrod}{ █ }}}$ 4.0%, 11.08 KB
dist/features/relationship	${{\color{Goldenrod}{ ▊ }}}$ 3.3%, 9.03 KB
dist/lexical/utils	${{\color{Goldenrod}{ ▊ }}}$ 3.1%, 8.49 KB
dist/features/debug	${{\color{Goldenrod}{ ▋ }}}$ 2.7%, 7.39 KB
dist/utilities/fieldsDrawer	${{\color{Goldenrod}{ ▋ }}}$ 2.6%, 7.15 KB
dist/features/converters	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 7.05 KB
dist/lexical/config	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 5.08 KB
dist/features/lists	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 5.00 KB
dist/features/format	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 3.46 KB
dist/lexical/LexicalEditor.js	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 3.22 KB
dist/lexical/theme	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 2.62 KB
dist/field/Field.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 2.59 KB
(other)	${{\color{Goldenrod}{ █████████████████████▊ }}}$ 87.2%, 241.93 KB

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

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████▎ }}}$ 49.3%, 579.02 KB
dist/elements/FolderView	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 29.37 KB
dist/elements/BulkUpload	${{\color{Goldenrod}{ ▌ }}}$ 2.4%, 27.80 KB
dist/views/Edit	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 17.30 KB
dist/elements/WhereBuilder	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 17.29 KB
dist/forms/Form	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 15.85 KB
dist/fields/Relationship	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.78 KB
dist/elements/Table	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.77 KB
dist/fields/Upload	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 14.24 KB
dist/fields/Blocks	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 13.89 KB
dist/elements/QueryPresets	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 10.36 KB
dist/elements/PublishButton	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 9.09 KB
dist/providers/Folders	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.47 KB
dist/elements/HTMLDiff	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.38 KB
dist/elements/ListHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.99 KB
dist/fields/Array	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.73 KB
dist/views/CollectionFolder	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.50 KB
dist/views/List	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.35 KB
dist/elements/ReactSelect	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.33 KB
dist/elements/LivePreview	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.02 KB
(other)	${{\color{Goldenrod}{ ████████████▋ }}}$ 50.7%, 594.78 KB

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

Path	Size
dist/graphics/Logo	${{\color{Goldenrod}{ █████ }}}$ 20.0%, 3.12 KB
../../node_modules	${{\color{Goldenrod}{ ████▎ }}}$ 17.0%, 2.65 KB
dist/graphics/Icon	${{\color{Goldenrod}{ ██▍ }}}$ 9.8%, 1.52 KB
dist/utilities/formatDocTitle	${{\color{Goldenrod}{ ██▏ }}}$ 8.5%, 1.32 KB
dist/providers/TableColumns	${{\color{Goldenrod}{ █▍ }}}$ 5.5%, 862 B
dist/utilities/groupNavItems.js	${{\color{Goldenrod}{ █▎ }}}$ 5.2%, 814 B
dist/utilities/getGlobalData.js	${{\color{Goldenrod}{ █▏ }}}$ 4.9%, 762 B
dist/utilities/api.js	${{\color{Goldenrod}{ █▏ }}}$ 4.8%, 756 B
dist/elements/Translation	${{\color{Goldenrod}{ ▊ }}}$ 3.2%, 493 B
dist/utilities/handleTakeOver.js	${{\color{Goldenrod}{ ▋ }}}$ 2.8%, 440 B
dist/utilities/traverseForLocalizedFields.js	${{\color{Goldenrod}{ ▋ }}}$ 2.6%, 399 B
dist/elements/withMergedProps	${{\color{Goldenrod}{ ▌ }}}$ 2.2%, 339 B
dist/utilities/getVisibleEntities.js	${{\color{Goldenrod}{ ▌ }}}$ 2.1%, 329 B
dist/utilities/getNavGroups.js	${{\color{Goldenrod}{ ▍ }}}$ 1.9%, 301 B
dist/elements/WithServerSideProps	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 232 B
dist/utilities/handleGoBack.js	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 180 B
dist/fields/mergeFieldStyles.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 159 B
dist/utilities/handleBackToDashboard.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 152 B
dist/forms/Form	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 147 B
dist/utilities/abortAndIgnore.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 146 B
(other)	${{\color{Goldenrod}{ ████████████████████ }}}$ 80.0%, 12.51 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.

jacobsfletch · 2026-03-19T20:52:10Z

+            {shouldRenderIframe && (
+              <IframeLoader
+                id="live-preview-iframe"
+                onLoad={() => {


This is all the same behavior as before, just abstracted away and handled through callbacks instead.

jacobsfletch · 2026-03-19T20:54:01Z

+ */
+const livePreviewIframeID = 'live-preview-iframe'
+
+export const getLivePreviewIframe = async (


Standardizing the test locators here and strengthening its tests.

jacobsfletch · 2026-03-19T20:55:07Z

+ * 1. Only show if the load takes longer than x ms.
+ * 2. Once shown, force it to be visible for at least x ms to avoid flickering, even if the iframe loads before then.
+ */
+export const IframeLoader: React.FC<IframeLoaderProps> = ({


Most notable changes are in this new component, which is abstract enough to use elsewhere throughout our UI over time.

github-actions · 2026-04-01T01:16:39Z

🚀 This is included in version v3.81.0

jacobsfletch added 2 commits March 19, 2026 12:39

retrofit iframeloader

b6b2cb1

rm old iframe component, execute onLoadFromProps

894a22c

github-actions Bot added the created-by: Payload team label Mar 19, 2026

jacobsfletch marked this pull request as ready for review March 19, 2026 17:24

jacobsfletch requested review from AlessioGr and JarrodMFlesch as code owners March 19, 2026 17:24

jacobsfletch added 2 commits March 19, 2026 13:56

fix tests

c37b921

improve test helper

c677ab0

jacobsfletch changed the title ~~feat(ui): iframe loader~~ refactor(ui): live preview iframe loader Mar 19, 2026

jacobsfletch added 3 commits March 19, 2026 16:22

deflake a11y test

6bc1076

Merge branch 'main' into feat/iframe-loader

bea2fc7

adjust shimmer to allow transparent bg

fe3042d

jacobsfletch commented Mar 19, 2026

View reviewed changes

jacobsfletch added 3 commits March 19, 2026 17:03

fix iframe ref

713794f

fix test helper

62450be

fix final test and add back classname for backward compat

c87b5ab

jacobsfletch enabled auto-merge (squash) March 20, 2026 13:29

AlessioGr approved these changes Mar 20, 2026

View reviewed changes

jacobsfletch merged commit 167a01e into main Mar 20, 2026
152 checks passed

jacobsfletch deleted the feat/iframe-loader branch March 20, 2026 22:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(ui): live preview iframe loader#16004

refactor(ui): live preview iframe loader#16004
jacobsfletch merged 10 commits into
mainfrom
feat/iframe-loader

jacobsfletch commented Mar 19, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Mar 19, 2026 •

edited

Loading

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

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

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

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

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

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

Uh oh!

jacobsfletch Mar 19, 2026 •

edited

Loading

Uh oh!

jacobsfletch Mar 19, 2026

Uh oh!

jacobsfletch Mar 19, 2026 •

edited

Loading

Uh oh!

Uh oh!

github-actions Bot commented Apr 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jacobsfletch commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 esbuild Bundle Analysis for payload

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

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

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

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

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

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

Uh oh!

jacobsfletch Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jacobsfletch Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

jacobsfletch Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Apr 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jacobsfletch commented Mar 19, 2026 •

edited

Loading

github-actions Bot commented Mar 19, 2026 •

edited

Loading

jacobsfletch Mar 19, 2026 •

edited

Loading

jacobsfletch Mar 19, 2026 •

edited

Loading