Fix ability to preview Additional CSS changes in the Customizer when using a Block Theme #70428

westonruter · 2025-06-14T20:44:09Z

The implementation here is described in https://core.trac.wordpress.org/ticket/63589#comment:23

Instead of re-introducing the separate STYLE tag for the Customizer's Custom CSS in the Customizer Preview just for the sake of live preview, in my new approach I'm surrounding the Customizer's Custom CSS in CSS comments. These are used to locate where the Customizer's Custom CSS appears in the overall global styles so that the Customizer Preview JS logic can surgically insert the updates into the existing inline stylesheet.

This will ensure that the Custom CSS in the Customizer Preview will look exactly the same as the frontend, since the CSS cascade will be the same.

The new approach is now part of WordPress/wordpress-develop#9000

Obsolete Approach

Adding the Additional CSS from the Customizer to the global styles makes sense, except not in the Customizer preview. This is because wp-includes/js/customize-preview.js is supposed to dynamically update the STYLE#wp-custom-css element with the new stylesheet whenever it changes. So this PR prevents putting the Additional CSS into the global styles when in the Customizer preview context.

In the Customizer preview, this PR prevents injecting the Customizer's CSS into the global-styles in between the global stylesheet and the Custom CSS. Instead, it prints the Customizer's Custom CSS before printing other styles. This ensures that the CSS cascade is preserved for global styles. However, normally the Customizer's CSS is printed at wp_head priority 101, long after the wp_print_styles() runs at priority 8. This was to ensure that the Customizer's Custom CSS would be able to override any and all styles added by the theme or plugins; however, in a block theme the Customizer's Custom CSS is already being deprioritized.

See the diff for how * { color: blue; } in the Customizer and * { color: red; } in global styles Custom CSS appear in the Customizer preview and outside in the normal view:

--- frontend.prettier.html	2025-07-07 18:26:17
+++ customizer-preview.prettier.html	2025-07-07 18:26:08
@@ -539,6 +542,11 @@
 					});
 			})(window, document, window._wpemojiSettings);
 		</script>
+		<style id="wp-custom-css">
+			* {
+				color: blue;
+			}
+		</style>
 		<link
 			rel="stylesheet"
 			id="dashicons-css"
@@ -2284,9 +2298,6 @@
 				font-family: var(
 					--wp--preset--font-family--fira-code
 				) !important;
 			}
-			* {
-				color: blue;
-			}
 			* {
 				color: red;

This issue was introduced in #58991

Screencast

Before

Screen.Recording.2025-06-14.at.13.28.10.mov

After

Screen.Recording.2025-06-14.at.13.31.21.mov

github-actions · 2025-06-14T20:44:19Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: westonruter <westonruter@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

WordPress/wordpress-develop#9000 #70428

lib/script-loader.php

…ix/custom-css-customize-preview

github-actions · 2025-07-08T01:20:36Z

Flaky tests detected in 37846e0.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/16613818055
📝 Reported issues:

[Flaky Test] Redirection after template creation #60678 in /test/e2e/specs/site-editor/site-editor-url-navigation.spec.js

…tomizer styles in cascade

…ix/custom-css-customize-preview

westonruter · 2025-07-28T04:46:14Z

I've marked this as a draft now because the core PR now has a better approach, as described in https://core.trac.wordpress.org/ticket/63589#comment:23

…reviewing

Co-authored-by: Peter Wilson <peterwilsoncc@git.wordpress.org>

t-hamano · 2025-07-29T07:55:08Z

lib/script-loader.php

+ *
+ * Note: The logic in this function would be back-ported into customize-preview.js.
+ */
+function gutenberg_add_customizer_block_theme_custom_css_preview_js() {


If WordPress/wordpress-develop#9000 will be shipped with WP 6.9, can we move this code into the lib/compat/wordpress-6.9 directory? Once the minimum supported version of WordPress for Gutenberg increases to 6.9, this code will no longer be necessary and can be removed.

How about 37846e0?

t-hamano · 2025-07-29T08:02:48Z

lib/script-loader.php

+		sprintf( '( %s )( %s )', $js_function, wp_json_encode( $setting_id ) )
+	);
+}
+add_action( 'wp_enqueue_scripts', 'gutenberg_add_customizer_block_theme_custom_css_preview_js' );


I haven't tested it to see if it works, but can we use the customize_preview_init hook to avoid unnecessary function execution on the frontend? This hook seems to be widely used in default themes to enqueue scripts as well.

So like this?

add_action( 'customize_preview_init', static function () { add_action( 'wp_enqueue_scripts', 'gutenberg_add_customizer_block_theme_custom_css_preview_js' ); } );

This would then eliminate the need for the is_customize_preview() check in the function.

Actually, there's not really any need to use wp_enqueue_scripts here. We're just adding an inline script to a script that already registered. So this can be:

Suggested change

add_action( 'wp_enqueue_scripts', 'gutenberg_add_customizer_block_theme_custom_css_preview_js' );

add_action( 'customize_preview_init', 'gutenberg_add_customizer_block_theme_custom_css_preview_js' );

See d9f7988

lib/script-loader.php

Co-authored-by: t-hamano <wildworks@git.wordpress.org>

t-hamano

This PR works correctly on both WordPress 6.7, which the Gutenberg plugin supports, and the latest core trunk.

t-hamano · 2025-07-30T13:42:09Z

lib/compat/wordpress-6.9/customizer-preview-custom-css.php

+
+if ( version_compare( get_bloginfo( 'version' ), '6.9.0', '<' ) ) {
+	add_action( 'customize_preview_init', 'gutenberg_add_customizer_block_theme_custom_css_preview_js' );
+}


This conditional statement will return true if WordPress is in Alpha or Beta, or RC, so the action hook will run even if the JS logic has already been merged into core.

Finally, I would suggest one of the following changes:

Remove the conditional statement because there is a skip process here.

Use is_wp_version_compatible(), which allows us to compare with he pure version number:

if ( is_wp_version_compatible( '6.9' ) ) { add_action( 'customize_preview_init', 'gutenberg_add_customizer_block_theme_custom_css_preview_js' ); }

@t-hamano I included both on purpose actually… I wanted to avoid adding that additional JS when in 6.9 stable. But for 6.9-alpha, I thought it was fine to include it for the sake of devs on different nightly versions.

I see, if that's your intention, I think the code is fine as is 👍

…using a Block Theme (#70428) * Fix ability to preview Custom CSS changes in the Customizer * Add backport changelog WordPress/wordpress-develop#9000 WordPress/gutenberg#70428 * Undo unnecessary update to deprecated function * Ensure global styles are shown in Customizer preview and override Customizer styles in cascade * Add Customizer details to the comment * Update Customizer Custom CSS inside of global styles for live preview * Make sure saved milestone comments are removed from stored CSS when previewing * Add line breaks before/after Custom CSS for readability/debugging Co-authored-by: Peter Wilson <peterwilsoncc@git.wordpress.org> * Remove erroneous duplicated appending of global styles custom CSS * Simplify adding inline script to customize-preview Co-authored-by: t-hamano <wildworks@git.wordpress.org> * Improve JS formatting * Add commit reference * Move custom CSS preview logic to 6.9 compat include Co-authored-by: t-hamano <wildworks@git.wordpress.org> --------- Co-authored-by: westonruter <westonruter@git.wordpress.org> Co-authored-by: t-hamano <wildworks@git.wordpress.org> Co-authored-by: Peter Wilson <peterwilsoncc@git.wordpress.org> Source: WordPress/gutenberg@9b3d784

…using a Block Theme (WordPress#70428) * Fix ability to preview Custom CSS changes in the Customizer * Add backport changelog WordPress/wordpress-develop#9000 WordPress#70428 * Undo unnecessary update to deprecated function * Ensure global styles are shown in Customizer preview and override Customizer styles in cascade * Add Customizer details to the comment * Update Customizer Custom CSS inside of global styles for live preview * Make sure saved milestone comments are removed from stored CSS when previewing * Add line breaks before/after Custom CSS for readability/debugging Co-authored-by: Peter Wilson <peterwilsoncc@git.wordpress.org> * Remove erroneous duplicated appending of global styles custom CSS * Simplify adding inline script to customize-preview Co-authored-by: t-hamano <wildworks@git.wordpress.org> * Improve JS formatting * Add commit reference * Move custom CSS preview logic to 6.9 compat include Co-authored-by: t-hamano <wildworks@git.wordpress.org> --------- Co-authored-by: westonruter <westonruter@git.wordpress.org> Co-authored-by: t-hamano <wildworks@git.wordpress.org> Co-authored-by: Peter Wilson <peterwilsoncc@git.wordpress.org>

Fix ability to preview Custom CSS changes in the Customizer

87be9ed

westonruter requested a review from spacedmonkey as a code owner June 14, 2025 20:44

westonruter requested review from tellthemachines and removed request for spacedmonkey June 14, 2025 20:44

westonruter added a commit to westonruter/wordpress-develop that referenced this pull request Jun 18, 2025

Backport WordPress/gutenberg#70428

1debf45

westonruter mentioned this pull request Jun 18, 2025

Fix ability to preview Additional CSS changes in the Customizer in Block Themes WordPress/wordpress-develop#9000

Closed

westonruter added a commit that referenced this pull request Jun 18, 2025

Add backport changelog

617ca2d

WordPress/wordpress-develop#9000 #70428

Add backport changelog

259b5fc

WordPress/wordpress-develop#9000 #70428

westonruter force-pushed the fix/custom-css-customize-preview branch from 617ca2d to 259b5fc Compare June 18, 2025 00:53

westonruter commented Jun 26, 2025

View reviewed changes

lib/script-loader.php Outdated Show resolved Hide resolved

westonruter requested a review from peterwilsoncc June 26, 2025 21:35

westonruter and others added 3 commits June 26, 2025 14:35

Merge branch 'trunk' of https://github.com/WordPress/gutenberg into f…

390d17b

…ix/custom-css-customize-preview

Merge branch 'trunk' of https://github.com/WordPress/gutenberg into f…

a8e9257

…ix/custom-css-customize-preview

Undo unnecessary update to deprecated function

494425a

westonruter added 3 commits July 7, 2025 18:22

Ensure global styles are shown in Customizer preview and override Cus…

8a0c67a

…tomizer styles in cascade

Add Customizer details to the comment

31ac0a9

Merge branch 'trunk' of https://github.com/WordPress/gutenberg into f…

2b725fe

…ix/custom-css-customize-preview

westonruter marked this pull request as draft July 28, 2025 04:45

Update Customizer Custom CSS inside of global styles for live preview

5d2390c

westonruter marked this pull request as ready for review July 28, 2025 05:04

westonruter and others added 3 commits July 27, 2025 22:34

Make sure saved milestone comments are removed from stored CSS when p…

cc4d3cf

…reviewing

Add line breaks before/after Custom CSS for readability/debugging

9b73223

Co-authored-by: Peter Wilson <peterwilsoncc@git.wordpress.org>

Remove erroneous duplicated appending of global styles custom CSS

8a2cd2a

t-hamano reviewed Jul 29, 2025

View reviewed changes

westonruter commented Jul 29, 2025

View reviewed changes

lib/script-loader.php Outdated Show resolved Hide resolved

westonruter and others added 4 commits July 29, 2025 21:25

Simplify adding inline script to customize-preview

d9f7988

Co-authored-by: t-hamano <wildworks@git.wordpress.org>

Improve JS formatting

6af3e0f

Add commit reference

3ed8be2

Move custom CSS preview logic to 6.9 compat include

37846e0

Co-authored-by: t-hamano <wildworks@git.wordpress.org>

westonruter requested a review from t-hamano July 30, 2025 05:00

t-hamano approved these changes Jul 30, 2025

View reviewed changes

t-hamano removed the Needs PHP backport Needs PHP backport to Core label Jul 30, 2025

westonruter changed the title ~~Fix ability to preview Additional CSS changes in the Customizer~~ Fix ability to preview Additional CSS changes in the Customizer when using a Block Theme Jul 30, 2025

westonruter merged commit 9b3d784 into trunk Jul 30, 2025
68 of 72 checks passed

westonruter deleted the fix/custom-css-customize-preview branch July 30, 2025 16:11

github-actions bot added this to the Gutenberg 21.4 milestone Jul 30, 2025

	add_action( 'wp_enqueue_scripts', 'gutenberg_add_customizer_block_theme_custom_css_preview_js' );
	add_action( 'customize_preview_init', 'gutenberg_add_customizer_block_theme_custom_css_preview_js' );

Fix ability to preview Additional CSS changes in the Customizer when using a Block Theme #70428

Fix ability to preview Additional CSS changes in the Customizer when using a Block Theme #70428

Uh oh!

Conversation

westonruter commented Jun 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Screencast

Before

After

Uh oh!

github-actions bot commented Jun 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jul 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

westonruter commented Jul 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

t-hamano left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

westonruter commented Jun 14, 2025 •

edited

Loading

github-actions bot commented Jun 14, 2025 •

edited

Loading

github-actions bot commented Jul 8, 2025 •

edited

Loading