Block Variations

What are block variations

The Block variation API as the name implies is a means of presenting multiple variations of the same block. One examples of this is the Embed Block which presents in the Block Library as the Youtube Block, Spotify Block Vimeo Block etc. Another example is the Columns Block which shows up in the Block Library only as the column block, but upon insertion will present a number of presets such as 50/50, 30/70, 33/33/33.

Additionally multiple blocks can be used in tandem and/or nested, and presented as an original block variation.

How variations modify blocks and their limitations

Block variations do not added or augment additional functionality or styling, but rather work with what’s already there by redefining existing settings. With that said every Block Variation can be given its own Name, Title, Description, and Icon, in addition to numerous other settings. Here is a list of all the fields that can be specified in a Block Variation https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/#defining-a-block-variation

Creating & Naming a Block Variation

In the Child Starter Theme, variations live in the ../src/blocks/_variations/ directory

Creating a block variation

Block variations can be declared during a block’s registration by providing the variations key with a proper array of variation objects, as shown in the example above. See the Block Registration API for more details.

To create a variation for an existing block, such as a Core block, use wp.blocks.registerBlockVariation(). This function accepts the name of the block and the object defining the variation.

wp.blocks.registerBlockVariation( 'core/embed', {
    name: 'custom-embed',
    attributes: { providerNameSlug: 'custom' },
} );

Registering block variations in PHP

Block variations can also be registered from PHP using the get_block_type_variations filter hook. This approach is particularly useful when you need to dynamically generate variations based on registered post types, taxonomies, or other WordPress data.

Here’s an example of how to register a custom variation for the core/image block:

function my_custom_image_variation( $variations, $block_type ) {
    // Only modify variations for the image block
    if ( 'core/image' !== $block_type->name ) {
        return $variations;
    }

    // Add a custom variation
    $variations[] = array(
        'name'        => 'wide-image',
        'title'       => __( 'Wide image', 'textdomain' ),
        'description' => __( 'A wide image', 'textdomain' ),
        'scope'       => array( 'inserter' ),
        'isDefault'   => false,
        'attributes'  => array(
            'align' => 'wide', // Identifies the link type as custom
        ),
    );

    return $variations;
}
add_filter( 'get_block_type_variations', 'my_custom_image_variation', 10, 2 );

The get_block_type_variations filter is called when variations are requested for a block type. It receives two parameters:

• $variations: An array of currently registered variations for the block type
• $block_type: The full block type object

Note that variations registered through PHP will be merged with any variations registered through JavaScript using registerBlockVariation().

Removing a block variation

Block variations can also be easily removed. To do so, use wp.blocks.unregisterBlockVariation(). This function accepts the name of the block and the name of the variation that should be unregistered.

wp.blocks.unregisterBlockVariation( 'core/embed', 'youtube' );

Additional Resources

For more information see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/