Block variations

What are block variations?

Block variations are easily confused with block styles.
With a block style, you can change how the block looks with CSS, and the style can be selected in the editor.
And with a block variation, you change the block settings and create a variation with those presets.

One example of block variations is the columns block, where you can select the number of columns when you add the block.

In this lesson I want to create a block variation for a full width group block.
A full width group block is one of the blocks that will be used most with full site editing, because they work great as inner wrappers inside template parts.

I want a faster way to add the full width block, and I want to set it as my default.
-There are several different ways to do this, but for this tutorial I wanted to create a variation.

How to register a block variation

Block variations can only be registered using JavaScript. You can read more about it in the official documentation.

Enqueue the JavaScript file for the editor

Create a new empty JavaScript file called block-variations.js.

Create a new PHP function, for example in the themes functions.php file (Don’t forget to update the prefix in the code example).

By using enqueue_block_editor_assets you can load the script only in the block editor.

function prefix_editor_assets() { wp_enqueue_script( 'prefix-block-variations', get_template_directory_uri() . '/assets/block-variations.js' ); } add_action( 'enqueue_block_editor_assets', 'prefix_editor_assets' );
Code language: JavaScript (javascript)

To be able to register a variation, you also need to include wp.blocks as a dependency. Add this last inside wp_enqueue_script:

function prefix_editor_assets() { wp_enqueue_script( 'prefix-block-variations', get_template_directory_uri() . '/assets/block-variations.js', array( 'wp-blocks' ) ); } add_action( 'enqueue_block_editor_assets', 'prefix_editor_assets' );
Code language: PHP (php)

Register the block variation

Inside the JavaScript file you can now call registerBlockVariation with wp.blocks:

wp.blocks.registerBlockVariation( );
Code language: CSS (css)

Add the block type inside the parenthesis. In this example I am using the group block:

wp.blocks.registerBlockVariation( 'core/group', { } );
Code language: JavaScript (javascript)

Just like when registering a block pattern, our variation needs a name
that is a unique identifier, and a title, which is the visible name or label in the editor.

You can also add an optional description and icon to the variation.
If you don’t add an icon, the groups default icon will be used.

wp.blocks.registerBlockVariation( 'core/group', { name: 'full-width-group', title: 'Full width group', } );
Code language: JavaScript (javascript)

You can now save your JavaScript file and test it in the block editor.
You should find that your variation is available and that the block works,
but because we have not added any attributes yet, it is not full width.

Add the attributes object after the title and update the align attribute to full:

wp.blocks.registerBlockVariation( 'core/group', { name: 'full-width-group', title: 'Full width group', attributes: { align: 'full' } } );
Code language: JavaScript (javascript)

In the editor, you can now use the shortcut /full to add your full width group block.

Attributes are unique to the block type that you have chosen to work with.
You can find the attributes that a block supports in the block reference.

Making the variation the default

All you need to make the variation the default is one more line: isDefault: true.

wp.blocks.registerBlockVariation( 'core/group', { name: 'full-width-group', title: 'Full width group', attributes: { align: 'full' }, isDefault: true } );
Code language: JavaScript (javascript)