Extending the editor with block styles is a quick way to add, or remove, styling defaults to any Gutenberg block.

Among adding block patterns and variations, block styles are a clever way to standardize creative elements of a site running on Gutenberg. I suspect that in time, block styles will become a core component of block themes, alongside block patterns, as they both enable creativity and flare.

And while it is relatively simple to add block styles using PHP, removing them is not quite as easy—especially block styles added by WordPress core (or any added client-side).

Enter Javascript… and I promise, it’s not as daunting as you might think. This article is one of a series of posts I’ve shared since I’ve started diving into building a full site editing block theme for my blog.

Extending block styles using PHP

While I don’t recommend using PHP to register block styles, as it’s server-side, and are difficult for others to remove — I do think it is important to understand how these PHP functions relate with their Javascript equivalents.

1. Registering block styles

So here’s how to register a block style using PHP and the register_block_style() function, referencing the block name and an array of properties.

/**
 * Block Styles
 */
function rich_register_block_styles() {

	if ( function_exists( 'register_block_style' ) ) {

		register_block_style(
			'core/image',
			array(
				'name'  => 'bottom-right',
				'label' => __( 'Bottom Right', 'rich' ),
			)
		);
		
		register_block_style(
			'core/image',
			array(
				'name'  => 'bottom-left',
				'label' => __( 'Bottom Left', 'rich' ),
			)
		);

		register_block_style(
			'core/image',
			array(
				'name'  => 'center',
				'label' => __( 'Center', 'rich' ),
			)
		);
	}
}
add_action( 'after_setup_theme', 'rich_register_block_styles' );

You may also use the inline_style property to add an inline style for the block style, or the style_handle property to pull in styles from a stylesheet that is registered for use on the site. You may learn a bit more on these style properties here — but I’m not using them, as I’m just including the styles in my personal block theme’s stylesheet. While you’ll need to follow up with CSS styling within the theme, the block style UI components for each of these are now accessible within the Styles panel of the core/image block.

2. Unregistering block styles

And here’s how to unregister one of the block styles that I added in the example above with the unregister_block_style() function, once again using PHP:

function rich_unregister_block_styles() {

	if ( function_exists( 'unregister_block_style' ) ) {
		unregister_block_style( 'core/image', 'center' );
	}
}
add_action( 'after_setup_theme', 'rich_unregister_block_styles');

Now, here’s the catch about unregistering block styles: the PHP function only works on block styles that were registered on the server using the corresponding register_block_style() function from above. All block styles registered client-side (that is, using Javascript) will not be unregistered by the PHP unregister_block_style() function.

Hence, the reason I recommend going ahead and using Javascript for both registering and unregistering block styles—because you need to anyhow to unregister them.

Extending block styles using Javascript

Now let’s use the PHP examples from earlier as we dive into the Javascript implementations. The process of updating themes and plugins to register block styles with Javascript would look very similar to what we do here. So there are two steps you’ll need to complete to register, and unregister block styles within Gutenberg: enqueuing an editor script, and adding the functions.

1. Enqueuing an editor script

Add a function to enqueue the script, within your theme’s functions.php file. You will use the enqueue_block_editor_assets() hook to specify assets that should load within the block editor. The function to enqueue the script should relatively close to this example, but with your own prefixes and script location:

function rich_block_editor_scripts() {
	wp_enqueue_script( 'rich-editor', get_theme_file_uri( '/assets/js/block-styles.js' ), array( 'wp-blocks', 'wp-dom' ), wp_get_theme()->get( 'Version' ), true );}
add_action( 'enqueue_block_editor_assets', 'rich_block_editor_scripts' );

Once added, the Javascript file should be loading within admin pages that are running the block editor. There’s no need to hook up Webpack or setup @wordpress/scripts — nothing of the sort.

2. Adding and removing Gutenberg block styles

Open up the script referenced in the example above and use the registerBlockStyle function to register new block styles like this:

wp.domReady( () => {

	wp.blocks.registerBlockStyle( 
		'core/image', {
			name: 'bottom-right',
			label: 'Bottom Right',
		}
	);

	wp.blocks.registerBlockStyle( 
		'core/image', {
			name: 'bottom-left',
			label: 'Bottom Left',
		}
	);

	wp.blocks.registerBlockStyle( 
		'core/image', {
			name: 'center',
			label: 'Center',
		}
	);

} );

These are the same block styles I created in the earlier PHP example, but migrated to Javascript. Next, removing block styles that have been added by WordPress core (or any other theme or plugin) can be done by using unregisterBlockStyle, like this:

wp.domReady( () => {

	wp.blocks.unregisterBlockStyle(
		'core/image', [ 'rounded' ]
	);

} );

In the example above I’m first referencing the block, then the block style I want removed entirely. With this snippet, I’ve removed the core “Rounded” block style from the Image block. I don’t plan on using that effect on my blog’s images — so now it’s successfully unregistered and I don’t have it cluttering the interface. You may even combine the registering and unregistering of block styles together in one file like this:

wp.domReady( () => {

	wp.blocks.unregisterBlockStyle(
		'core/image', [ 'rounded' ]
	);

	wp.blocks.registerBlockStyle( 
		'core/image', {
			name: 'bottom-right',
			label: 'Bottom Right',
		}
	);

	wp.blocks.registerBlockStyle( 
		'core/image', {
			name: 'bottom-left',
			label: 'Bottom Left',
		}
	);

	wp.blocks.registerBlockStyle( 
		'core/image', {
			name: 'center',
			label: 'Center',
		}
	);

} );

Finish it up a bit of CSS and you have a default block style and three standardized, and creative ways to showcase images throughout a site. This is what I plan on using on my blog here when I refresh it shortly:

That’s it. Now you know how to properly register and deregister block styles using Javascript. That wasn’t so bad, was it? Are you using block styles in a creative way?