Featured

What is a custom block style?

A custom block style is a style change that is applied to a WordPress block to make it look different from the default styles.

The difference between a custom block style and a custom block, is that the style is added to existing blocks, while custom blocks are new blocks that may add new functionality. It is usually simpler to create custom styles than entire blocks.

The custom block style can then be selected in the WordPress editor:

An image describing the settings for the gallery block in the WordPress editor. A new block style called Hide captions is available for selection.
Example of a custom style added to a gallery block.

How a custom style is added

The code to add the styles consists of JavaScript, CSS and two PHP functions. It can be included in your theme, child theme, or a plugin.

The JavaScript adds the functionality to the editor that lets you select the new style. The CSS is used both in the editor and the front.

If you want to know more, you can continue with this tutorial: How to add a block style to a child theme.

Combining more than one block style

In the first example, we only included one custom block style. Adding more styles is straightforward, so lets look at some examples and minor optimization tips.

Adding more than one style to the JavaScript file

We can combine several style options into one JavaScript file as illustrated in the example below:

wp.blocks.registerBlockStyle('core/image', { 
   name: 'slug-filter-grayscale', label: wp.i18n.__('Filter: Grayscale', 'text-domain')
});

wp.blocks.registerBlockStyle('core/image', { 
   name: 'slug-filter-sepia', label: wp.i18n.__('Filter: Sepia', 'text-domain') 
});

We are using wp.blocks.registerBlockStyle separately for each option. Then we are telling the script which block we want to use: ‘core/image’. Finally we are giving the option a name and a translatable label.

Adding more than one style to the CSS file

Adding additional CSS is even simpler:

.is-style-slug-filter-sepia img {
	filter: sepia(100%);
}

.is-style-slug-filter-grayscale img {
	filter: grayscale(100%);
}

Remember to use the correct selector. In this example we have the is-style-, then the name of the option and img, since we are adding a filter to the image block.

Optimizing the PHP functions

First, we want to check if the theme already uses the hooks ‘enqueue_block_editor_assets’ and / or ‘enqueue_block_assets’. If they are already used, we want to extend the functions and add our code to them, instead of using the hooks twice.

To illustrate this with an example, the theme Twenty Nineteen uses the following code to add extra styles:

/**
 * Enqueue supplemental block editor styles.
 */
function twentynineteen_editor_customizer_styles() {

	wp_enqueue_style( 'twentynineteen-editor-customizer-styles', get_theme_file_uri( '/style-editor-customizer.css' ), false, '1.1', 'all' );

	if ( 'custom' === get_theme_mod( 'primary_color' ) ) {
		// Include color patterns.
		require_once get_parent_theme_file_path( '/inc/color-patterns.php' );
		wp_add_inline_style( 'twentynineteen-editor-customizer-styles', twentynineteen_custom_colors_css() );
	}
}
add_action( 'enqueue_block_editor_assets', 'twentynineteen_editor_customizer_styles' );

What we want to do is enqueue our JavaScript file (block-style.js) inside the function twentynineteen_editor_customizer_styles(). This will save us the effort of creating our own function. 🙂

/**
 * Enqueue supplemental block editor styles.
 */
function twentynineteen_editor_customizer_styles() {

	wp_enqueue_style( 'twentynineteen-editor-customizer-styles', get_theme_file_uri( '/style-editor-customizer.css' ), false, '1.1', 'all' );

	if ( 'custom' === get_theme_mod( 'primary_color' ) ) {
		// Include color patterns.
		require_once get_parent_theme_file_path( '/inc/color-patterns.php' );
		wp_add_inline_style( 'twentynineteen-editor-customizer-styles', twentynineteen_custom_colors_css() );
	}

	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', 'twentynineteen_editor_customizer_styles' );

To recap, we are:

  • Adding the block-styles.js which adds the style options to the WordPress editor.
  • Adding 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.
  • Enabling the translations with wp_set_script_translations, the script name, and the text domain.

There is more than one way to add the styles

We still need to add our custom CSS, and there is more than one way to do this.

  • You can enqueue your CSS file (which only contains the custom block styles) with the ‘enqueue_block_assets’ hook, as we did in the previous example.
  • If your theme is already using ‘enqueue_block_editor_assets’ to include styles for the editor, you have the option to add your CSS to your themes existing .css files. This means that you have to add the styles twice: Once in the file that is used for the editor, and once for the front end.

Which option to choose depends on the size of the CSS. In this example we are only adding two styles, so the second option might be better since we are avoiding the additional http request. But if the file is larger, -or if you really don’t want to have to repeat yourself, the first option might be better.

How to add a custom block style to a child theme

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.

Ready for step two?