Custom block styles

Level: ,

Estimated reading time: 5 minutes

Last updated: February 19, 2022.

What are custom block styles?

Custom block styles are all about adding new styles to existing blocks.
The difference between just styling a block and adding a custom block style is that the custom block style is available as an option in the editor interface.

Custom block styles have been available in WordPress since version 5.3.0. They do not require the Gutenberg plugin or full site editing.

You can preview and select styles in the block settings sidebar panel. Custom block styles are often simplistic. It can be a text shadow or a border around a paragraph block. An example of a block style added by WordPress is the rounded image:

Image blocks with a custom block style that adds rounded corners. When the setting is hovered or focused on, a preview of the style is shown.
The interface may look different if you do not have Gutenberg active.

There are no additional settings when a user selects a custom block style. For example, if you add a style with a box shadow, you can not adjust the color, spread, or opacity using the interface.

How do custom block styles work?

Block styles work by adding a CSS class to the block and applying styles to the new selector. When you have selected a block style, you can open the Advanced section of the block settings sidebar and see that WordPress adds the class in the Additional CSS class(es) field.

How to create custom block styles

You can register the custom block style with PHP or with JavaScript. Which method you choose depends on personal preference and how you wish to organize your theme files.
Official documentation.

Registering block styles using PHP

You can use the PHP function register_block_style() to create a single style. Place the function in your themes functions.php file, or use a separate file if you prefer.

register_block_style( string $block_name, array $style_properties )

$block_name
(string) (Required) 
Block type name including namespace.

$style_properties
(array) (Required) 
Array containing the properties of the 
style name, 
label,
style (name of the stylesheet to be enqueued),
inline_style (string containing the CSS to be added).

First, you need to tell the function which block you want to style. In this example, I am using the core paragraph block. I am adding the prefix, core, and paragraph, the slug for the block, as the first argument:

register_block_style(
'core/paragraph',
     array(
        'name'  => 'prefix-rounded-corners',
	'label' => __( 'Rounded corners (Requires background color)', 'textdomain' ),
        'inline_style' => '.is-style-prefix-rounded-corners {  
	   border-radius: 6px;
        }',
    )

);

The second argument is an array, where you will add the name, which is the CSS class that identifies your style, and the label, which is the visible name in the block settings sidebar.

Then you have a decision to make about where you want your CSS to be. You can use the inline style or add a handle for a stylesheet that you are already enqueueing.
When you choose the inline CSS option, you add all your CSS as a value in inline_style.

The format for the generated class name is is-style- followed by the value that you added to the name property: is-style-prefix-rounded-corners.
There is no way to customize the is-style- addition: Instead, you need to adapt your CSS to include this selector.

If your CSS is complex, you may also need to escape certain characters:

'inline_style' => '.wp-block-separator.is-style-prefix-ornament {
 mask-image: url(\'data:image/svg+xml; utf8, <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 81.52 29.9">
	<path ... /></svg>\' );
 }',

If you add the style handle, remember to add the stylesheet to both the editor and the front.

You are not limited to styling blocks from WordPress core. If you know the prefix and the slug, you can also style blocks from plugins.

Registering custom block styles using JavaScript

To register a custom block style with JavaScript, you need to create a new JavaScript file and enqueue it together with the following dependencies: wp-blocks, wp-dom-ready, and
wp-edit-post. Without these dependencies, your style with not work correctly.

Instead of using wp_enqueue_scripts, you need to use enqueue_block_editor_assets to load the scripts in the editors.

Example adapted from the official documentation:

function myguten_enqueue() {
    wp_enqueue_script(
        'myguten-script',
        get_stylesheet_directory_uri() . '/assets/js/myguten.js',
        array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' ),
        filemtime( plugin_dir_path( __FILE__ ) . '/assets/js/myguten.js' )
    );
}
add_action( 'enqueue_block_editor_assets', 'myguten_enqueue' );

If you are not familiar with filemtime, the purpose here is to create a version number for the file used for development.

The JavaScript code in myguten.js:

wp.blocks.registerBlockStyle( 'core/quote', {
    name: 'fancy-quote',
    label: 'Fancy Quote',
} );

Finally, you also need to add the CSS for the generated CSS class to a stylesheet that you enqueue for both the editor and the front. Remember that the generated CSS selector is is-style-, followed the value inside name: is-style-fancy-quote.

How to unregister block styles

You can also unregister block styles. -This is a bit trickier than it needs to be, in my opinion: Styles registered with PHP can only be unregistered with PHP. Styles registered with JavaScript can only be unregistered with JavaScript.

To unregister a style with PHP, you need to use the function unregister_block_style(). Include the prefix, the block slug, and the name of the style:

unregister_block_style( 'core/quote', 'fancy-quote' );

Depending on how the style is registered, you need to use an action hook that runs after the one used for the registration; Another reason why unregistering styles can be complicated. -You may need to search the source code to find when the style is registered.

JavaScript example from the advanced theme that I am using in the block theme generator:

function full_site_editing_unregister_block_style() {
	wp_enqueue_script(
		'full-site-editing-unregister',
		get_stylesheet_directory_uri() . '/assets/js/unregister.js',
		array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' ),
		FULL_SITE_EDITING_VERSION,
		true
	);
}
add_action( 'enqueue_block_editor_assets', 'full_site_editing_unregister_block_style' );

The JavaScript code in unregister.js:

wp.domReady(() => {
	wp.blocks.unregisterBlockStyle('core/quote', 'large');
	wp.blocks.unregisterBlockStyle('core/quote', 'plain');
});

Additional notes

I have received questions about whether it is possible to select two block styles, but this is still not possible as of February 19, 2022. You can follow the discussion and progress on allowing multiple block styles here: Gutenberg #14598