How to Register a Block Style in WordPress

WordPress is moving towards a block based design. Full side editing is already here. To develop a theme you have to know how blocks work together to form a design.

There are some default core blocks that comes with an WordPress installation. WordPress has given us the option to style those blocks with a few clicks. The same can be done with a custom block also.

Let us see how the styling is done.

Take the example of the paragraph block. It is a core block. We can style it by registering a block style. Registering a block style simply means adding a CSS class to the block.

This can be done with PHP or JavaScript. I will illustrate both approach.

Register a block style in PHP

First, we have to know the name of the block with namespace. In the case of the paragraph block it is core/paragraph. The core is the namespace of the block.

[All WordPress core blocks have the namespace core]

Then we can register a style by using the function register_block_style.

if ( function_exists( 'register_block_style' ) ) {
    register_block_style(
        'core/paragraph',
        array(
            'name'         => 'highlighted-para',
            'label'        => __( 'Highlighted', 'textdomain' ),
            'inline_style' => '.is-style-highlighted-para{ 
                    color: #ffffff; 
                    background-color: #000000;
                    padding: 20px;
             }',
        )
    );
}

The function register_block_style takes two arguments. The first one is the name of the block (with namespace), and the second one takes an array of configurations.

The configuration array consists of name, label and an inline style array. Out of these, only name and label are required arguments.

What we are doing here is passing an inline styling to the block, but we can also skip the inline styling and write the style in a separate file.

Notice that the class-name of the inline style is is-style-highlighted-para. This name is derived from the name element of the argument highlighted-para. This is the required naming convention when we want to style a block. The class-name of the style derives from the name of the style!

This will add the CSS class is-style-highlighted-para to any paragraph that we apply the style to. We can apply the style from the right hand options that appear when the paragraph block is chosen in the post editor.

We can also move the inline styling to a new CSS file and then enqueue that file in WordPress. We have to maintain the naming convention of prefixing the class name with is-style.

if ( function_exists( 'register_block_style' ) ) {
    register_block_style(
        'core/paragraph',
        array(
            'name'         => 'highlighted-para',
            'label'        => __( 'Highlighted', 'textdomain' )           
        )
    );
}

Here we are using just the name and the label. We will move the CSS class to a separate file and then enqueue it.

add_action('enqueue_block_assets', 'w123_enqueue_resources');
function w123_enqueue_resources()
{
   wp_enqueue_style('highlighted_block_style', get_template_directory_uri() . '/css/highlighted_block_style.css' )   
}

Note that we are using enqueue_block_assets hook since the stylesheet needs to be added to the editor and frontend simultaneously.

Then contents of the highlighted_block_style.css file –

// highlighted_block_style.css
.is-style-highlighted-para 
{
    color: #ffffff; 
    background-color: #000000;
    padding: 20px;
}

In both cases, the result will look something like this –

You can click on the new style and see the affect on the editor screen. Note that the style does not have option for further manipulation. So you can not change the color, padding or add some other config to the style.

Registering a Block Style in JavaScript

A block style can also be registered using JavaScript. In fact this is the preferred method for registering a style for a block as WordPress is moving towards JavaScript editing.

We will use the hook enqueue_block_assets to add a JavaScript file –

add_action( 'enqueue_block_assets', 'x123_block_editor_scripts' );

function x123_block_editor_scripts()
{
    wp_enqueue_script( 
        'custom-block-style', 
        get_theme_file_uri( '/js/custom_block_style.js' ), 
        array( 'wp-blocks', 'wp-dom' ), 
        wp_get_theme()->get( 'Version' ), 
        true 
    );
}

In the callback function x123_block_editor_scripts of the hook enqueue_block_assets, we are enqueueing a JavaScript file custom_block_style.js that will contain the code for registering the block style.

Notice that we are also using wp-blocks and wp-dom as dependencies. These dependencies are required for the registration.

wp.domReady( () => {

	wp.blocks.registerBlockStyle( 
		'core/paragraph', {
		    name: 'highlighted-para',
		    label: 'Highlighted'
		}
	)
	
} )

We are using the wp object to check if the document is ready for manipulation, and then registering the style with registerBlockStyle.

[ The wp object is the main JavaScript object of WordPress and is available with every installation. It exposes a large number of methods and properties which we can use for DOM manipulation. ]

The next step is to enqueue a CSS style file with the required class name. We will do that inside the callback for enqueue_block_assets. So the updated code looks like –

add_action( 'enqueue_block_assets', 'x123_block_editor_scripts' );
function x123_block_editor_scripts() 
{
	wp_enqueue_script( 
        'custom-block-style', 
        get_theme_file_uri( '/js/custom_block_style.js' ), 
        array( 'wp-blocks', 'wp-dom' ), 
        wp_get_theme()->get( 'Version' ), 
        true 
    );
    wp_enqueue_style( 
        "highlighted",
        get_template_directory_uri() . '/css/highlighted.css',
        array()
    );
}

The CSS style file highlighted.css contains the CSS class name for the style –

// highlighted.css
.is-style-highlighted-para 
{
    color: #ffffff; 
    background-color: #000000;
    padding: 20px;
}

The output is same as Figure – Block Style above.

The paths for these CSS and JavaScript files can be changed to suit your site requirements.

Wordpress