Using multiple stylesheets per block

Prior to WordPress 5.9, each blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. could (but not required to) have a stylesheet attached to it. The way blocks could register a stylesheet was by adding a style and/or editorStyle string in their block.json file.

In WordPress 5.9 we’re enhancing that behavior to allow using multiple stylesheets to be registered for each block. This change can benefit both block developers and theme developers, further reducing the total page-weight by only loading styles for blocks that exist on a page.

Blocks will now be able to register multiple stylesheets, and load styles from other blocks when needed. Themes will be able to add styles on a per-block basis instead of loading monolithic stylesheets that are force-loaded anywhere. This has a greater impact on block themes where stylesheets loading is optimised based on the page & layout contents, but can also be used by classic themes.

Usage for block developers

The style and editorStyle properties inside a block.json file can now be either a string, or an array of strings. Each string can be the handle of a previously registered stylesheet, or a path relative to the block.json file’s path, prefixed with file:./.

If you already have a block that uses a string, you needn’t worry. Everything will continue to work as expected. This is not a breaking change as the values can be either an array or a string, to maintain backward-compatibility.

This allows for complex blocks to reuse styles they need from other blocks without the need to duplicate those styles. For example, the comment-form block in WordPress 5.9 doesn’t need to duplicate the button block’s styles, and can instead reuse these styles by adding them to the block.json file:

{
 	"style": [
		"wp-block-post-comments-form",
		"wp-block-buttons",
		"wp-block-button"
	]
}

The same applies to the editorStyle value: Block developers can now define an array of styles, using the same format as the style value.

Usage for theme developers

Theme developers can also register stylesheets on a per-block basis. This way, no unnecessary styles will be rendered on a page unless the block is rendered (assuming the theme is a block-theme, or has opted-in to load separate stylesheets in the case of classic themes).

To do that, a new wp_enqueue_block_style() function was introduced.

The wp_enqueue_block_style function

The wp_enqueue_block_style function accepts 2 arguments, both of which are required:

$block_name

(string, required)

The name of the block – including its prefix/domain. For example the block_name of the paragraph block is core/paragraph.

$args

(array, required)

The arguments are the same used in the wp_enqueue_style function:

$args = array(
	'handle' => 'my-theme-p-styles',
	'src'    => get_theme_file_uri( 'styles/blocks/paragraph.css' ),
	...
);

In addition to the default wp_enqueue_style arguments, you can also add a path argument. This will allow WordPress to inline small assets when possible – if the theme opts-in to that behavior.

Example

Registering an extra stylesheet for the site-title block from a theme:

add_action( 'after_setup_theme', function() {
	// Same args used for wp_enqueue_style().
	$args = array(
		'handle' => 'my-theme-site-title',
		'src'    => get_theme_file_uri( 'assets/blocks/site-title.css' ),
	);

	// Add "path" to allow inlining asset if the theme opts-in.
	$args['path'] = get_theme_file_path( 'assets/blocks/site-title.css' );

	// Enqueue asset.
	wp_enqueue_block_style( 'core/site-title', $args );
} );

WordPress 5.9 enhances the way stylesheets for blocks get loaded. Though these changes have not been ported to block scripts yet, in future releases we plan to sync the two APIs, so block scripts can take advantage of them as well.

props @gziolo for reviewing this post.

#dev-notes, #developer-documentation