Day 13: Creating Custom Block Styles in Gutenberg

Introduction

Welcome to Day 13 of the Gutenberg development series! In today’s article, we’ll be focusing on custom block styles. This feature allows you to offer different visual styles for a single block, making it easier for users to switch between design options without having to create or select a new block.

For example, you could offer a rounded button style and a flat button style for the same button block, allowing users to pick the design that fits their content best.

In this guide, you’ll learn how to:

• Register custom block styles.
• Apply custom styles to blocks in the editor.
• Create custom CSS to define the visual appearance of these styles.

What are Custom Block Styles in Gutenberg?

A block style is a predefined visual design that users can apply to a block. By providing multiple styles for a single block, you allow users to quickly change the block’s appearance without modifying the content.

WordPress offers some default block styles (like different heading sizes for the Heading block), but you can create and register custom styles to give users more flexibility and design options.

Step 1: Registering Custom Block Styles

Let’s start by registering a couple of custom styles for the core/button block. For this example, we’ll create two styles: Rounded Button and Flat Button.

1. Create a JavaScript File for Block Styles

Create a JavaScript file to register your block styles. You can name this file button-styles.js and place it in your theme or plugin directory.

// blocks/button-styles.js
import { registerBlockStyle } from '@wordpress/blocks';

// Register Rounded Button style
registerBlockStyle('core/button', {
    name: 'rounded-button',
    label: 'Rounded Button',
});

// Register Flat Button style
registerBlockStyle('core/button', {
    name: 'flat-button',
    label: 'Flat Button',
});

Explanation:

• registerBlockStyle: This function registers a custom style for a block. Here, we’re adding two styles for the core/button block: Rounded Button and Flat Button.
• name: The unique identifier for the style.
• label: The name of the style as it will appear in the block settings.

Step 2: Enqueuing the Script

Next, enqueue the script in your theme’s functions.php file so that the custom block styles are available in the editor.

function my_theme_enqueue_block_styles() {
    wp_enqueue_script(
        'my-theme-button-styles',
        get_template_directory_uri() . '/blocks/button-styles.js',
        array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' ),
        filemtime( get_template_directory() . '/blocks/button-styles.js' )
    );
}
add_action( 'enqueue_block_editor_assets', 'my_theme_enqueue_block_styles' );

This will load the button-styles.js file, making your custom block styles available in the Block Editor.

Step 3: Styling the Custom Block Styles

Now that the styles are registered, we need to define how each style looks using CSS. Add the following styles to your theme’s style.css file to apply the necessary visual changes for each block style.

/* Rounded Button Style */
.wp-block-button.is-style-rounded-button .wp-block-button__link {
    border-radius: 50px;
    background-color: #0073aa;
    color: #ffffff;
    padding: 10px 20px;
}

/* Flat Button Style */
.wp-block-button.is-style-flat-button .wp-block-button__link {
    border-radius: 0;
    background-color: #f1f1f1;
    color: #333333;
    padding: 10px 20px;
    border: 2px solid #333333;
}

Explanation:

• .is-style-{style-name}: The custom style class is automatically applied by WordPress when the user selects a block style. We use this class to apply specific CSS rules to each block style.
• Rounded Button: This style adds a rounded border and a blue background.
• Flat Button: This style removes the border-radius for a flat appearance and applies a light gray background with a darker border.

Step 4: Using Block Styles in the Editor

Now that you’ve registered and styled your custom block styles, it’s time to test them in the Block Editor.

1. Open the Block Editor:
   • Go to any post or page in WordPress and open the Block Editor.
2. Insert a Button Block:
   • Click the “+” button to add a block.
   • Search for Button and add it to your post.
3. Select a Custom Style:
   • Select the button block, then click on the “Block” tab in the right-hand sidebar.
   • You should see the custom styles listed under “Styles”. Choose either Rounded Button or Flat Button to apply that style to the button.
4. Preview and Publish:
   • After selecting the style, you can preview the button in the editor. Publish the post to see how it looks on the front end.

Step 5: Removing Block Styles (Optional)

If you want to remove certain block styles (for example, to clean up the block editor interface), you can do so using the unregisterBlockStyle function.

For example, to remove the default “Outline” style from the Button block:

import { unregisterBlockStyle } from '@wordpress/blocks';

wp.domReady(() => {
    unregisterBlockStyle('core/button', 'outline');
});

This will remove the Outline style from the button block, leaving only your custom styles available.

Best Practices for Custom Block Styles

1. Keep Styles Simple: Provide styles that are easy to understand and use. Avoid adding too many complex styles that could overwhelm users.
2. Use Descriptive Names: Give your custom styles meaningful names so users can easily identify what each style does.
3. Maintain Consistency: Ensure that your block styles match the overall design of your theme or plugin for a seamless user experience.

Conclusion: Enhancing User Experience with Custom Block Styles

Custom block styles are a simple but powerful way to offer multiple visual options for a single block. This feature makes it easier for users to apply consistent design elements without needing to modify the content or manually adjust CSS. By offering predefined styles, you streamline the content creation process while maintaining flexibility for users.

In this article, you’ve learned how to:

• Register custom block styles in Gutenberg.
• Enqueue the necessary scripts to make styles available in the editor.
• Style the block styles using CSS.
• Use and manage block styles in the WordPress editor.

In Day 14, we’ll explore dynamic block templates, where you can define default content structures that automatically populate when a user adds a specific block.