Prior to WordPress 5.9, each block 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