Block editor: Load custom block style only when used

Published: February 10, 2025 by Matze – Leave a comment Last update: February 16, 2025

If you don’t use separate core block assets loading, but register block styles, these styles are always loaded, even if not required. This adds unnecessary load, since CSS files will load even if they don’t apply.

Prerequisites

In my case, should_load_separate_core_block_assets was disabled as well as loading core block CSS as a whole (since they change(d) over time, but I consider them as public API, which should not introduce breaking changes, which they do – but that’s another story) to make sure only the CSS of the theme loads (which adds a custom version of core block styles). If you use the default, especially in a block theme, the problem I’m about to be solving here won’t eben occur.

Registering the block style

When registering a block style in my scenario, every time a block is rendered where I registered a block style to, even if the custom block style is not used, will be loaded as separate CSS file (since I’ve registered it with a CSS file). It won’t apply since the is-style-<my-style> class is not added to the block, and that’s what makes its loading unnecessary.

Before, my code looked like this:

$style_data = [
	'dependencies' => [],
	'handle' => 'my_custom_style',
	'uri' => \get_template_directory_uri() . '/assets/block-styles/my-custom-style.css',
	'version' => (string) \filemtime( \get_template_directory() . '/assets/block-styles/my-custom-style.css' ),
];

\wp_register_style( $style_data['handle'], $style_data['uri'], $style_data['dependencies'], $style_data['version'] );
\register_block_style(
	'core/button',
	[
		'name' => 'my-custom-style',
		'label' => \__( 'My custom style', 'my-theme' ),
		'style_handle' => $style_data['handle'],
	]
);
Code language: PHP (php)

This way I register a style asset first, which will then be used later via wp_enqueue_style, since it’s added as style_handle in the register_block_style function.

Enqueue manually

Instead of adding the style_handle to the register_block_style, use the render_block_{$this->name} filter to enqueue your custom style only when necessary. So first, remove line 14 from the code above, deleting the style_handle key from the array altogether.

Then, inside the filter, check whether the className with the format is-style-<my-style> exists, indicating the type of block style, and enqueue the block style only if it matches the class.

/**
 * Enqueue block styles.
 * 
 * @param	string	$block_content Block content
 * @param	array{blockName?: string, attrs: array{className?: string}}	$block Block data
 * @return	string Block content
 */
function my_theme_enqueue_block_styles( string $block_content, array $block ): string {
	$block_style_handles = [
		'my_custom_style',
	];
	
	foreach ( $block_style_handles as $block_style_handle ) {
		$block_style_name = \str_replace( '_', '-', $block_style_handle );
		
		if (
			! empty( $block['attrs']['className'] )
			&& \str_contains( $block['attrs']['className'], 'is-style-' . $block_style_name )
		) {
			\wp_enqueue_style( $block_style_handle );
		}
	}
	
	return $block_content;
}

\add_filter( 'render_block_core/button', 'my_theme_enqueue_block_styles', 10, 2 );
Code language: PHP (php)

Conclusion

Handling enqueued style files for classic or hybrid themes is still a thing and strictly necessary. Review your code each time you add some CSS, it might end up being loaded unexpectedly where you don’t want it to be.