Learn in this tutorial how to create custom block variations for the WordPress editor and add them to a theme.
You know I’m a big believer in taking advantage of the block editor, especially by extending its native capabilities.
An interesting way to do this is by creating block styles, so I have prepared several tutorials about it:
- Creating custom block styles for WordPress
- How to enable block styles to load separately in WordPress
- Create custom block styles for the image block inside a WordPress gallery
- How to create listings with SVG icons using block styles in WordPress
- Highlight the last post in WordPress query loop block
- How to create a grid notebook style in WordPress
As you can see from the examples above, block styles are a fantastic tool for modifying the layout of existing blocks, but they have the limitation that you cannot modify the structure of the blocks.
Block variations, on the other hand, allow you to customize the structure and add/remove/modify their inner blocks.
You will understand this much better by looking at an example.
This is the native WordPress media and text block:
And this is the result of the variation we are going to create in this tutorial:
Steps to create a block variation in WordPress
1. Register new variations
The first thing you need to do is to register the new variations.
To do this create a file called block-variations.js inside the /assets/js/ folder of your theme (if it doesn’t exist you can create it) with the following code:
In this case the variation contains the following fields:
core/media-text: the media and text block for which we are creating the variation.
name: internal name.
title: title of the block displayed in the editor.
isDefault: whether you want it to be the default style or not.
attributes: the attributes that are available for the block and that you want to modify.
innerBlocks: the block structure you want to display.
Although in this example we are using only 7 fields, there are more.
These are all the fields available when defining a block variation:
But lets continue with the previous example, in which you record a new variation of the media and text block.
In the attributes you indicate:
mediaPosition: to display the image on the right side.
backgroundColor: you indicate that the background color is
foreground(a CSS variable defined in the theme) but if you prefer you can use the hexadecimal color.
You also define the
innerBlocks field to contain:
- An H3 header block.
- A paragraph block.
Both with their respective placeholders. Of course, you can modify it to your liking.
By setting the
isDefault field to
false, both the original version and the new variation you have created will be available in the editor.
If you set it to
true, only the new variation you have created will be displayed (i.e. the variation replaces the native block).
In fact, this is an option that can be very useful as I will explain in future tutorials.
2. Enqueue the new styles
Once you have the file where you have registered the styles you must enqueue them to the theme. To do this, add the following snippet to the end of functions.php:
You can see that it is not a very complicated process and it can give a lot to play with.
This is just a simple example to inspire you to create your own blocks variations.
The WordPress block editor allows for a lot of customization possibilities. If you want to get the most out of it, creating block variations is a good way to do it and now you know how.
If you have any question, please leave it in the comments. And if you want to give me a suggestion for future snippets, please send it through the contact form.
Benefits of being a subscriber. 🙂