Day 20: Creating Custom Block Variations in Gutenberg

Introduction

Welcome to Day 20 of the Gutenberg series! In this article, we’ll explore custom block variations, a powerful feature that allows you to offer multiple predefined styles or presets for a single block. Instead of creating separate blocks for each variation, you can use block variations to provide different visual options or behaviors, making it easier for users to select the appropriate design without having to manually adjust settings.

In this guide, you’ll learn how to:

• Create and register custom block variations.
• Offer multiple visual styles for a block.
• Customize block attributes for different variations.

What are Block Variations in Gutenberg?

Block variations are predefined configurations for a block that users can select in the block settings. These variations allow you to define different attributes, styles, or settings for a single block type. For example, you might want to provide variations like Primary Button and Secondary Button for a button block, each with different colors or layouts.

Variations improve the user experience by making it easy to switch between predefined styles without manually adjusting each attribute.

Step 1: Creating a Basic Block Variation

Let’s start by creating a simple Button Block with two variations: Primary Button and Outline Button. Each variation will have different styles.

1. Register the Block with Variations

In your block registration file (e.g., blocks/button-block.js), define the block and its variations.

import { registerBlockType } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';
import { createElement } from '@wordpress/element';

registerBlockType('my-theme/button-block', {
    title: __('Button Block'),
    icon: 'button',
    category: 'my-custom-category',
    attributes: {
        label: {
            type: 'string',
            default: __('Click Me'),
        },
        className: {
            type: 'string',
            default: 'primary-button',
        },
    },
    edit: ({ attributes, setAttributes }) => {
        const { label, className } = attributes;

        return (
            <button className={className} onClick={() => alert('Button Clicked')}>
                {label}
            </button>
        );
    },
    save: ({ attributes }) => {
        const { label, className } = attributes;

        return <button className={className}>{label}</button>;
    },
});

// Register the block variations
wp.blocks.registerBlockVariation('my-theme/button-block', [
    {
        name: 'primary-button',
        title: __('Primary Button'),
        description: __('A bold, standout button.'),
        attributes: { className: 'primary-button' },
        icon: 'button',
    },
    {
        name: 'outline-button',
        title: __('Outline Button'),
        description: __('A button with an outline style.'),
        attributes: { className: 'outline-button' },
        icon: 'button',
    },
]);

Explanation:

• Attributes: We define the label and className attributes. The className determines the button’s style (e.g., primary or outline).
• Block Variations: We register two variations—Primary Button and Outline Button—with different className attributes that control the button’s style.

Step 2: Adding Styles for the Variations

Now that we have registered the block variations, we need to add custom styles for each variation. Add the following CSS to your theme’s style.css file:

/* Primary Button Style */
.primary-button {
    background-color: #0073aa;
    color: #ffffff;
    padding: 10px 20px;
    border: none;
    border-radius: 5px;
    font-weight: bold;
}

/* Outline Button Style */
.outline-button {
    background-color: transparent;
    color: #0073aa;
    padding: 10px 20px;
    border: 2px solid #0073aa;
    border-radius: 5px;
    font-weight: bold;
}

Explanation:

• .primary-button: This class applies a solid background color for the Primary Button variation.
• .outline-button: This class applies a transparent background with a blue border for the Outline Button variation.

Step 3: Using Block Variations in the Editor

Now that the block variations are set up, let’s test them in the Gutenberg editor.

1. Add the Block in the Editor

• Go to the WordPress Block Editor.
• Add the Button Block by clicking on the “+” icon and searching for the block.

2. Select a Block Variation

• Once the block is added, open the block toolbar and select the block variation from the available options (e.g., Primary Button or Outline Button).

3. Preview the Styles

• Each variation will display with its own predefined style (solid or outline). You can switch between the variations easily and see the different visual representations of the button.

Step 4: Testing and Customizing Block Variations

After adding the block variations, you should test them in both the Block Editor and on the front end to ensure they behave as expected.

1. Rebuild the Block:
   • Run your build command to ensure the block and its variations are properly loaded.

npm run build

2. Test the Variations in the Editor:
   • Add the block to a post or page and switch between the Primary and Outline button styles. Ensure that each variation displays correctly in the editor.
3. Check the Front-End Display:
   • Preview the post or page on the front end and confirm that the correct button style is applied for each variation.

Best Practices for Block Variations

1. Keep Variations Simple: Avoid overwhelming users with too many variations. Focus on providing a few key options that are useful and relevant.
2. Use Descriptive Names: Ensure that the names of your variations are descriptive and easy to understand, so users can quickly identify the correct option.
3. Apply Consistent Styling: Make sure the variations fit well within the overall design of your theme or plugin to ensure consistency across the site.

Conclusion: Enhancing User Experience with Block Variations

Block variations are an excellent way to provide users with multiple predefined styles or presets for a single block. By offering different visual representations or behaviors, you can simplify the editing process and give users more control over how their content is displayed without overwhelming them with manual settings.

In this article, you’ve learned how to:

• Define and register block variations.
• Apply different visual styles for each variation.
• Test and use block variations in the Gutenberg editor.

In Day 21, we’ll explore nested blocks, which allow you to create more complex layouts by nesting blocks inside other blocks.