Block Variations in WordPress: Instances of Existing Blocks

WordPress 5.4 introduced Block Variations, an API for defining instances of existing blocks. A variation can carry pre-filled custom attributes — including classes — and pre-configured inner blocks, and it registers as a separate block with its own name and optional icon.

A common use is a quote: a site with three display treatments for quotes can expose three variations so each is styled differently.

Variations vs. Styles: Where the Line Sits

Block Styles change a block's appearance. A Block Style is a way of adding a custom class to a block through the post editor's Block options. Registering a style against the core Quote block using the pattern from the Block Editor Handbook adds an .is-style-fancy-quote class to the Quote block settings:

wp.blocks.registerBlockStyle(
  'core/quote',
  {
    name: 'fancy-quote',
    label: 'Fancy Quote'
  },
);
Screenshot of the Block options in the WordPress post editor highlighting the options for a quote block. A "Fancy Quote" option is listed under Styles and the custom class name is in an Additional CSS Classes field.
We now have a Fancy Quote option in the Block options under “Styles” and the class for it filled in for us.

Variations can technically achieve the same result, but go further: they pre-fill custom attributes (classes included) and inner blocks, and they are registered as separate blocks that show up in the inserter under unique names.

Registering a Variation

The registration API closely mirrors the Block Style API. registerBlockVariation takes the block name — core/quote, in this case — and an object (or an array of objects) describing the variation:

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

On its own this only adds "Fancy Quote" to the list of available blocks:

Showing the Fancy Quote variation in the WordPress Block Inserter.
We now have two different “quote” blocks available to drop into the post.

To take full advantage of a variation, the describing object accepts the following fields:

  • name — the unique, machine-readable variation name; the examples on GitHub and the Make WordPress post suggest kebab-case.
  • title — the human-readable title shown under the icon in the Inserter.
  • description — shown in the Inserter as well; if empty, the default block description is used. Optional.
  • icon — a Dashicons slug, an SVG or an object; declared the same way as in registerBlockType. Optional.
  • isDefault — whether this variation is the default, false unless set. Setting it to true in this example would leave the Fancy Quote as the only Quote block available in the inserter. Optional.
  • attributes — values that override block attributes; these are block-specific, such as level for the Heading block or height for Spacer.
  • innerBlocks — initial configuration of nested blocks; only applies to blocks that support inner blocks, such as Columns, Cover or Group. Optional.
  • example — structured data for the block preview; undefined disables the preview. Identical to the example field in registerBlockType. Optional.
  • scope — the scopes in which the variation applies; defaults to all. Accepted values are block and inserter.

Why Add the Abstraction

Buttons in different widths

A design system with Fill and Outline buttons maps onto the default WordPress button styles: write CSS for each and no new styles or editor hacks are needed. A width spec of Regular, Wide and Full complicates things. The alternatives:

  1. Write two extra classes (say, .is-wide and .is-full), teach the client to add them via the editor's Advanced panel, and document what each one does.
  2. Register four new styles in Block options: Fill Wide, Fill Full, Outline Wide and Outline Full.

Filtering the button block to add a custom width control, or building a custom block from scratch, are two further options — heavy lifts for such a simple task. Two variations, Full and Wide, keep things clean while achieving the same as a custom class, and can be dropped straight into a post from the Block Inserter:

wp.blocks.registerBlockVariation(
  'core/buttons',
  [
    {
      name: 'wide',
      title: 'Wide Buttons',
      attributes: {
        className: 'is-wide'
      },
  },
  {
      name: 'full',
      title: 'Full Buttons',
      attributes: {
        className: 'is-full'
      },
    }
  ]
);
Showing the Wide and Full button variations in the WordPress Block Inserter.
Button variations in the inserter

The lesson: variations do not replace styles and can work well alongside them, even when a variation only adds a class; and multiple variations can be registered in a single declaration.

Repeating column layouts

A portfolio case study intro — project name, client information, role description — is tedious to rebuild for every new study, since the Client and My Role headings never change; only the main title and two paragraphs are edited. A variation of the core Columns block called Project Intro can ship the columns and inner blocks already in place. Start by registering it:

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

Take it further with a portfolio icon from the Dashicons library, which is baked into WordPress, set via 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'],
    ],
  }
);

The block then appears in the block menu with that icon:

Variation with a custom icon in the Block Inserter.

The inner blocks are configured next:

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

Alone, this produces three empty columns. Starter content goes inside each of them using the same pattern as declaring a block template in the InnerBlocks component: an object with block attributes as the second array element describing the block, and an array of inner blocks as the third. The first column:

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

The complete variation:

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

Clicking — a few times, but fewer than without the variation — now inserts the whole section.

A four-column layout and the scope option

Columns is a default block type with several built-in layout options, but a four-column layout is not among them; several core blocks, Columns included, already offer variations that can be picked after inserting the block. If a site uses four columns as often as two, there is no shortcut button, and reaching the Columns control after insertion costs extra clicks.

A variation can create the four-column layout, and this time it makes more sense for it to sit inside the block placeholder next to the other column layouts rather than in the Inserter. That is what the scope option is for: setting it to [block] keeps the variation out of the Block Inserter and shows it among the variations once the block is 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'],
    ],
  }
);
Four-column layout variation scoped to the block.
Hey, now we have a four-column option!

The full SVG code for the icon is omitted here but available separately.

Summarizing scope: when it is not declared, the variation appears in the Block Inserter and inside the block placeholder — specifically for blocks that support block-scoped variations. Without the scope parameter, the example above would show in the inserter as follows:

Four-column block variation in the block inserter.
Keep in mind that the icon sizes for variations within the block and and the block icons size are different. The custom icon for columns was intended for the block scope, that’s why it looks a bit out-of-place in this example.

Choosing Between the Customization APIs

  • Block Styles — for altering a block's appearance when adding a CSS class is enough.
  • Block Variations — for specifying a block's default attributes and/or adding inner blocks to it.
  • Filtering the block or building a new block — when the markup itself must change.

Resources