How to add a custom block style to a child theme

In this guide I have written about how to add block styles using client side rendering. You may be interested in the new quick guide for server side rendering, which is available in WordPress version 5.3 and newer, and contains a lot less code and fewer steps.

Firstly, when you want to make changes to a theme, it is important that you use a child theme. Otherwise, your changes will be lost when the theme is updated.

You can learn how to create a child theme here:
https://developer.wordpress.org/themes/advanced-topics/child-themes/

In this example, we are going to add a custom block style to the gallery which hides the image captions.

We will create one JavaScript (.js) file and one CSS file, and then include them by editing functions.php.

Create a new file called block-style.js:

wp.blocks.registerBlockStyle('core/gallery', {
	name: 'slug-hide-caption',
	label: wp.i18n.__('Hide captions', 'text-domain')
});

On the first line we are registering a new block style and telling the script which block we want to style: ‘core/gallery’.

On line two, we are giving a name to our new style. Note that we are prefixing the name with our slug, to separate it from other styles.

And on the next line, we are adding the label, the human readable text that will be visible in the editor.

We are using wp.1l8n. together with the WordPress translation function and our text-domain to assure that the label can be translated.

Create a new file called custom-block-style.css:

.is-style-slug-hide-caption figcaption {
    display: none;
 }

Here we are using a selector which is a CSS class that is common for editor blocks: is-style. We are combining it with the name we choose earlier, and targeting the element that we want to style.

In this example, we are hiding the fig caption with display: none. This is a simple example, and other styles may include many more lines and be more complex.

The reason why we can not simply include the styles in our main CSS file, is that we want to use the styles both in the editor and on the front. Our themes main stylesheet, style.css is only loaded on the front (and in the customizer).

Editing functions.php

Open your child themes functions.php file. We are now going to make sure that the files we just created are included correctly. Copy and paste the following code, and don’t forget to change your slug and your text domain:

function slug_editor_assets() {
wp_enqueue_script( 'slug-block-styles-script', get_theme_file_uri( '/js/block-styles.js' ), array( 'wp-blocks', 'wp-i18n' ) );
wp_set_script_translations( 'slug-block-styles-script', 'text-domain' );
}

add_action( 'enqueue_block_editor_assets', 'slug_editor_assets' );

In this code example, we have placed the block-styles.js file in a folder in our themes directory called js. This is optional, just make sure that the path to the file is correct.

The next step is to add an array of existing block editor scripts that we need to include for our code to work: wp-blocks, for the block itself, and wp-il8n, for the translation function.

We use the hook enqueue_block_editor_assets to enqueue the files for the editor.

Next copy and paste the code below into functions.php:

function slug_block_styles() {
	wp_enqueue_style( 'slug-block-styles', get_theme_file_uri( '/css/custom-block-styles.css' ), false );
}
add_action( 'enqueue_block_assets', 'slug_block_styles' );

In this code example, we have placed the custom-block-styles.css file in a folder in our themes directory called css. This is optional, just make sure that the path to the file is correct.

We use the hook enqueue_block_assets to enqueue the files for both the editor and the front so that the block styles are applied correctly.

Save the functions.php file, open the editor, add a gallery block and test your new style:

An image describing the settings for the gallery block in the WordPress editor. A custom block style called Hide captions is available for selection.

That’s all! I hope this was not too complicated. If you have any questions or suggestions for improvements you can email me at hi@wpblockstyles.com.

Create a new file called block-style.js:

Create a new file called custom-block-style.css:

Editing functions.php

Recommended reading: