Adding a Custom Block Style

– an exercise in block customisation

This post is part of a series exploring how to customise a core block in the WordPress Block Editor. Our example is aiming to offer the option of a “true parallax” effect on the Block Editor Cover Block.

Having added the parallax javascript, a cover block on the page with class of “is-style-true-parallax” will cause the parallax Javascript to take effect. We now investigate how to add a custom Block Style, which will add the “is-style-true-parallax” class, when the user chooses the “True Parallax” option.

Note that “block style”, in this context, is an official term for the choices of named, pre-configured styles which appear in the settings sidebar styles tab for a block. An example of this is the choice of Default, Wide Line or Dots for the Separator block.

Adding a Block Style

This is how the True Parallax block style appears to the user, in the sidebar settings for the Cover block.

There appear to be two alternative methods for adding a block style – one using PHP and the other using Javascript.

PHP Method

The following code is added to functions.php in the theme, or in a plugin file (with appropriate changes to file location):-

function webl_block_styles() {
    // Register Block Style for Cover Block
    register_block_style (
        'core/cover',
        array(
            'name' => 'true-parallax',
            'label'=> 'True Parallax',
        )
    );
}
add_action( 'init', 'webl_block_styles' );

This is enough to automatically wrap the block in class:-

.is-style-true-parallax

In this case, the very presence of that class will cause our true-bg-parallax.min.js to kick in, if it is set up to activate based on:-

.wp-block-cover.is-style-true-parallax

Adding Additional CSS for a Block

If other styling is required, it can be added directly inline via the register_block_style eg

register_block_style (
    'core/cover',
    array(
        'name' => 'true-parallax',
        'label'=> 'True Parallax',
	'inline_style' => '.wp-block-cover.is-style-true-parallax { color: red; }'
    )
);

A larger amount of CSS can be added within the theme or plugin’s stylesheet, or in a block-specific stylesheet. Using a block stylesheet often offers better performance by only loading the block’s CSS if the block is in use on a page. On the front end, it will also inline this code within the <head> area.

Create and save a CSS stylesheet containing the styles you want to add for this specific block.

Enqueue the block CSS within the function which is added to the init action (eg webl_block_styles() above):-

function webl_block_styles() {
    ...
    wp_enqueue_block_style( 'core/cover', array(
	'handle' => 'webl-block-cover',
	'src'    => get_theme_file_uri( 'assets/css/true-parallax-cover.css' ),
	'path'   => get_theme_file_path( 'assets/css/true-parallax-cover.css' ),
        'ver'    => '0.0.1' 
    ) );
}
add_action( 'init', 'webl_block_styles' );

However, we do not require any additional CSS in this case, all we need is the simple block style registration, which will automatically add the class we need.

Javascript Method

The following code is added to functions.php in the theme, or in a plugin file (with appropriate changes to file location) to enqueue our block javascript:-

// Enqueue Block Styles
function webl_blockstyle_enqueue() {
    wp_enqueue_script(
        'webl-blockstyle-script',
        get_stylesheet_directory_uri() . '/assets/js/block-style.js',
	array( 'wp-blocks', 'wp-dom-ready', 'wp-element', 'wp-primitives' ),
	'0.0.1' 
    );
}
add_action( 'enqueue_block_editor_assets', 'webl_blockstyle_enqueue' );

The file block-style.js contains only:-

// Registering custom style called True Parallax
wp.blocks.registerBlockStyle( 'core/cover', {
    name: 'true-parallax',
    label: 'True Parallax',
} );

This is enough to automatically wrap the block in class

.is-style-true-parallax

In this case, the very presence of that class will cause our true-bg-parallax.min.js to kick in, if it is set up to activate based on:-

.wp-block-cover.is-style-true-parallax

If other styling is required, it must be added within the theme or plugin’s stylesheet, or in a block-specific stylesheet, or via theme.json. Inline CSS cannot be added via the javascript registerBlockStyle method.

Adding a custom block style for the cover block

This option uses a Block Style which has been added to the Cover Block.

It is quite simple to add a “block style” choice. It appears near the top of the style tab for the block. Choosing it adds class ‘is-style-true-parallax’ to the block, which should enable parallax on the front end.

Alternative Methods for Customising a Block

Adding a Block Variation
Using Block Filters