Full Site Editing

Estimated reading time: 4 minutes

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 block’s settings sidebar in the editor. With a block variation, you change the block settings and create a variation with those presets.

One example of a block variation is the columns block, where you can select the number of columns:

In this beginner 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 wrappers for other blocks. 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. The JavaScript file needs to be enqueued in the editors, but is not needed on the front of your website.

First, create a new empty JavaScript file called block-variations.js. Next, 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 in the block editor and site 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' );

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' );

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

wp.blocks.registerBlockVariation(

);

Add the block prefix and the block slug inside the parenthesis. In this example, I am using the group block:

wp.blocks.registerBlockVariation(
	'core/group',
	{
		
	}
);

Just like when registering a block pattern, the variation needs a name as the 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. The icon can be an icon name from Gutenberg, or a custom SVG code for example. If you don’t add an icon, the group’s default icon will be used.

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

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'
		}
	}
);

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 use block variations to override or disable block attributes. 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
	}
);

Specification

So far, I have showed you how to use the parameters name, title, attributes and isDefault. I also mentioned that the attributes are unique to the block. There are several parameters that you can take advantage of depending on what you want to achieve: I will show you some of them in lesson two. Please see the official documentation for a complete list.

• description: Similar to the title and icon, you can override the block description.
• innerBlocks: Prepopulate the variation with an array of inner blocks.
• scope: Choose where the variation should show up, in the block inserter or transform panel (below the block information in the block settings sidebar).

Resources

Variations

https://developer.wordpress.org/news/2022/12/building-a-book-review-grid-with-a-query-loop-block-variation/