Webmasters Gallery

WordPress 5.4 was released not so long ago and, along with other improvements and bug fixes, it introduced a feature called Block Variations. I had a chance to use it on one of my recent projects and am so pleasantly surprised with how smart this feature is. I actually think it hasn’t received the attention it deserves, which is why I decided to write this article.

What is a Block Variation?

Block Variations allow developers to define instances of existing blocks. An example that you’ll see below is a quote block. Perhaps your site has three variations of how to display a quote on your site. A Block Variation can be created for each one so that they are all styled differently. This sounds awfully familiar with how Block Styles, but the concept of variations goes a bit further than that, as we’ll see.

How are Block Variations different from Block Styles?

Fair question. Block variations appear in the inserter as separate blocks with unique names and (optionally) icons and can have pre-filled custom attributes, and inner blocks.

Block Styles are designed to alter the look of the block. In fact, a Block Style is a fancy way of adding a custom class to a block using the Block options in the post editor.

The difference is clear when you consider how each one is used in the post editor. Let’s say we register a new Block Style called “Fancy Quote.” We do that by extending the core “Quote” block like this example from the Block Editor Handbook:

wp.blocks.registerBlockStyle(
  'core/quote',
  {
    name: 'fancy-quote',
    label: 'Fancy Quote'
  },
);

This adds a .is-style-fancy-quote class to the Quote block settings in the post editor.

Even though it sort of sounds like it would do the same thing (which it technically can), a Block Variation can be used to pre-fill custom attributes (including custom classes) and inner blocks. They’re actually registered as separate blocks.

Let’s take a closer look at the API and what block variations can do.

Creating a Block Variation

The API for registering Block Variations is very similar that of the Block Style we just looked at:

wp.blocks.registerBlockVariation(
  'core/quote',
  {
    name: 'fancy-quote',
    title: 'Fancy Quote',
  },
);

The registerBlockVariation function accepts the name of the block (in our case it is core/quote) and an object (or an array of objects) describing the variation(s).

The code above doesn’t do much by default, but it does add “Fancy Quote” to the list of available blocks.

To take full advantage of the variation. we need to provide more details in the object describing it. The list is covered in the Make WordPress post, but I’ll share it here and provide additional comments.

• name – The unique and machine-readable name of the variation. Following the examples on Github and Make post it’s safe to assume that the best practice is to use kebab-case for naming variations.
• title – A human-readable variation title. This is what appears under the icon in the Inserter.
• description – A detailed variation description. Appears in the Inserter as well. If empty, the default block description will be used. (Optional)
• icon – An icon for the variation. Can be a Dashicons slug, an SVG or an object. Follows the same declaration pattern as in registerBlockType. (Optional)
• isDefault – Indicates whether the current variation is the default one. Defaults to false. In case of our example, if we set it to true, the Fancy Quote block will be the only Quote block available in the inserter. (Optional)
• attributes – Values that override block attributes. These are block-specific. You can set the level for the Heading block or height for Spacer, for example.
• innerBlocks – Initial configuration of nested blocks. Only applies to blocks that allow inner blocks in the first place, like Columns, Cover, or Group. We’ll cover this in one of the examples. (Optional)
• example – Example provides structured data for the block preview. You can set it to undefined to disable the preview shown for the block type. This is the same as the example field in registerBlockType. (Optional) There’s more information available on this parameter.
• scope – The list of scopes where the variation is applicable. When not provided, it assumes all available scopes. Available options are block and inserter. We’ll cover this in detail in one of the examples.

Many of you may wonder why we need this extra layer of abstraction. Let me try to answer that with a few use cases (one form my recent project).

Use case: Buttons with different widths

Let’s say you have a design system with two types of buttons: Fill and Outline.

Lucky you, because these are the default styles for buttons in WordPress. No need to register any new styles or hack the editor. All you have to do is write some CSS for each style and call it a day. Life is good and everybody’s happy.

But then you look in the design spec again and notice that there is a little twist. The buttons come in three widths: Regular, Wide, and Full.

Dammit! You are a little upset because you now have two options:

1. Write two extra classes for the new button sizes (say, .is-wide and .is-full), then teach the client to use the Advanced panel in the editor to add those classes and write a manual where you explain what each class does. Or…
2. Register four(!) new styles that go in the Block options: Fill Wide, Fill Full, Outline Wide, and Outline Full.

Neither of those options are exactly elegant. (BTW, what is Fill Full exactly? Quite an unfortunate mouthful!)

There are two more options that I didn’t include in the list:

• Filter the button block and add a custom width control to it
• Build a custom block from scratch.

These obviously feel like heavy lifts for such a simple task.

Enter Block Variations! By adding just two variations, Full and Wide, we can keep things clean and simple:

wp.blocks.registerBlockVariation(
  'core/buttons',
  [
    {
      name: 'wide',
      title: 'Wide Buttons',
      attributes: {
        className: 'is-wide'
      },
  },
  {
      name: 'full',
      title: 'Full Buttons',
      attributes: {
        className: 'is-full'
      },
    }
  ]
);

This is the same as adding a custom class to the Buttons block, but in a neat and elegant way that can be dropped directly into a post from the Block Inserter:

Life is good and everybody is happy again! So what did we learn from this example?

• It shows that Block Variations are not designed to replace Block Styles. In fact, they can work pretty well together even if the variation just adds a class to a block.
• It demos how to register multiple variations in a single declaration.

Use case: Repeating column layouts

Let’s say you are a designer and have a portfolio website with case studies. Each case study has an intro section with the name of the project, client information, and a description of your role on the project. It might look something like this:

The problem is that it’s a bit tedious to build this part of the layout every time you create a new portfolio case study — especially because the Client and My Role headings never change. You are only editing the main title and two paragraphs.

With Block Variations, you can create a variation of a core Columns block called Project Intro that will have the columns, and inner blocks already defined. This example is a bit more involved, so we’ll build it out step-by-step.

Let’s start with registering the variation:

wp.blocks.registerBlockVariation(
  'core/columns', {
    name: 'project-intro',
    title: 'Project Intro',
    scope: ['inserter'],
    innerBlocks: [
      ['core/column'],
      ['core/column'],
      ['core/column'],
    ],
  }
);

We are taking this example a bit further than the first one, so why not add a custom portfolio icon from the Dashicons library that’s baked right into WordPress? We do that with the icon property.

wp.blocks.registerBlockVariation(
  'core/columns', {
    name: 'project-intro',
    title: 'Project Intro',
    icon: 'portfolio',
    scope: ['inserter'],
    innerBlocks: [
      ['core/column'],
      ['core/column'],
      ['core/column'],
    ],
  }
);

This will make the block available in the block menu with our icon:

The next important thing happens on where we add inner blocks:

wp.blocks.registerBlockVariation(
  'core/columns', {
    name: 'project-intro',
    title: 'Project Intro',
    icon: 'portfolio',
    scope: ['inserter'],
    innerBlocks: [
      ['core/column'],
      ['core/column'],
      ['core/column'],
    ],
  }
);

But this only gives us three empty columns. Let’s add starter content and inner blocks to each of them. We can use the same pattern we use to declare a block template in the InnerBlocks component. We can add an object with block attributes as a second element in the array describing the block, and an array of inner blocks as the third element.

The first column will look like this:

['core/column', {}, [
  ['core/heading', { level: 2, placeholder: 'Project Title'} ],
]]

…and the complete block variation is like this:

wp.blocks.registerBlockVariation (
  'core/columns', {
    name: 'project-intro',
    title: 'Project Intro',
    icon: 'portfolio',
    scope: ['inserter'],
    innerBlocks: [
      ['core/column', {}, [
        ['core/heading', { level: 2, placeholder: 'Project Title' }],
      ]],
      ['core/column', {}, [
        ['core/heading', { level: 3, content: 'Client' }],
        ['core/paragraph', { placeholder: 'Enter client info' }],
      ]],
      ['core/column', {}, [
        ['core/heading', { level: 3, content: 'My Role' }],
        ['core/paragraph', { placeholder: 'Describe your role' }],
      ]],
    ],
  }
);

Cool, now we can insert the whole section with just one click. Okay, it’s a few clicks, but still faster than without using the variations.

So what did we learn from this example?

• And demos how to use the inner blocks within the variation
• It shows how to define a custom icon for a variation

Use case: Four-column layout

You already know that columns are a default block type, and that there are a handful of options for different types of columns. A four-column layout isn’t one of them, so we can build that. But this introduces a new concept as well: scoping in context of block variations.

Some core blocks, like Columns, already offer variations out of the box. You can choose one of them after you insert the block on the page:

Let’s say you use a four-column layout on your website as often as you use two-column one. That’s unfortunate, because there is no shortcut button to create four-column layout. Creating one is a bit annoying because it takes extra clicks to get to the Columns control after the block is inserted:

So, what can you do to improve this workflow? Right, you can add a Block Variation that will create a four-column layout. The only difference this time, compared to previous examples, is that it makes much more sense to include this variation inside the block placeholder, next to all other column layouts.

That is exactly what the scope option is for. If you set it to [block], the variation will not appear in the Block Inserter but in the variations once the block has been inserted.

wp.blocks.registerBlockVariation(
  'core/columns', {
    name: 'four-columns',
    title: 'Four columns; equal split',
    icon: <svg ... />,
    scope: ['block'], // Highlight
    innerBlocks: [
      ['core/column'],
      ['core/column'],
      ['core/column'],
      ['core/column'],
    ],
  }
);

Isn’t that sweet?!

I’ve omitted the full SVG code for the icon, but it’s available if you need it.

To sum up scope: If it isn’t declared, the variation will appear in the Block Inserter and inside the block placeholder — specifically for blocks that support block-scoped variations.

If we were to remove the scope parameter from the example above, here’s how the variation would appear in the inserter:

So what did we learn from this example?

• It explains the difference between the block and inserter scope for the variation.
• We learned how to use SVG for variation icon.

That’s it!

As you can see, Block Variations are pretty powerful for building a lot of things, from different variations of buttons to complete page layouts.

I’d like to wrap this up with a quick recap of different APIs for block customizations and when to use them:

• Use Block Styles if you need to alter the appearance of the block and adding a CSS class is enough for that.
• Use Block Variations if you need to specify the default attributes for the block and/or add inner blocks to it.
• If that’s not enough and you need to change the markup of the block, you are probably looking into filtering the block or creating a new one from scratch.

If you’ve had a chance to play with Block Variation, let me know what you think of them in the comments!

Resources

• Make WordPress Post
• GitHub Pull Request #20068

The post How to Use Block Variations in WordPress appeared first on CSS-Tricks.