Create custom variations for WordPress blocks

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:

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:

Here’s how:

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:

To see this and another 1097 code snippets of this website, login or subscribe here.

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:

name (required)
title (required)
description
category
icon
isDefault
attributes
innerBlocks
example
scope:
- inserter
- block
- transform
keywords
isActive

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 can see the exact attributes of each block in the official documentation.

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.

Media and text blocks 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:

To see this and another 1097 code snippets of this website, login or subscribe here.

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.

Conclusions

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. 🙂