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

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:

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 inregisterBlockType. Optional.isDefault— whether this variation is the default,falseunless set. Setting it totruein 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 aslevelfor the Heading block orheightfor 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;undefineddisables the preview. Identical to the example field inregisterBlockType. Optional.scope— the scopes in which the variation applies; defaults to all. Accepted values areblockandinserter.
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:
- Write two extra classes (say,
.is-wideand.is-full), teach the client to add them via the editor's Advanced panel, and document what each one does. - 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'
},
}
]
);

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:

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

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:

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.



