Now is an exciting time for WordPress developers with the official release of version 5.0 just around the corner. This will mark the debut of the brand new editor, code-named Gutenberg. If you have anything to do with WordPress on a regular basis, whether as a developer or as a user, then you’ll probably understand why this is big news.
Not everyone’s looking forward to the new release, though, as it does bring a very different editing experience to WordPress. There is a bit of uncertainty about how this will affect the broader WordPress ecosystem. However, the new editor has the potential to revolutionize how you create content for WordPress sites. And even though it may meet with initial resistance when it hits users en masse, I think it could ultimately give a much more tangible connection with your content in a way that isn’t possible with the classic TinyMCE editor.
You can try out the new editor ahead of the planned WordPress 5.0 release by installing the Gutenberg plugin from the WordPress plugin repository. If you’ve not had the chance to try it out yet then I’d strongly recommend you do so, to get a preview of the future editing experience in WordPress!
Creating content in the new editor is entirely block based. Every piece of content you add to the editor is a block. This includes all your favorite elements such as sliders, paragraphs, buttons, lists, images, testimonials, and so on. Once a block is added to the editor, you can configure settings that control its appearance and behavior. These can be edited either on the block itself or via the inspector panel (located to the right of the editor screen). Block settings are sometimes duplicated in both locations, but this varies from block to block.
Almost all blocks, though, have an option in the inspector panel to manually add one or more CSS class names to allow further block customization. This can be very useful if you wish to override styles for a core block or third-party block.
While this works fine, it would be beneficial to extend this behavior and allow block customization options to be added via a set of predefined style choices. This is exactly what block style variations give us, and we’ll be focusing on them exclusively throughout this tutorial.
Prerequisites
We’ll also be taking a look at how to add block style variations to your own blocks as well as how to extend existing blocks, so in order to follow along, you’ll ideally need to be familiar with the basics of WordPress plugin development and how blocks are created.
Don’t panic, though—if you need a crash course then check out my four-part tutorial on creating custom blocks. It covers pretty much everything that you need to know for this tutorial—apart from block style variations, the focus of this particular tutorial!
Also, if you want to follow along with the code and try it out yourself then you’ll need a local development server to run WordPress on (e.g. WAMP, MAMP or the like), and a code editor.
Background
The block style variations API was introduced to the Gutenberg project in v3.2 of the plugin and allows you to apply alternative block styles directly via the editor interface.
To achieve the same result prior to block style variations, you had to manually enter custom CSS classes in the Additional CSS Class text field in the block inspector panel, located under the Advanced section.
If you’re interested in the original proposal for block style variations then you can read up on the full details in the pull request in the official Gutenberg repo.
Any style variations defined for a block can be accessed directly in the block toolbar. Select the block, and then click the top left icon on the toolbar to display the Block Styles pane.
Remember earlier when I said some blocks settings can be accessed directly on the block and in the inspector panel? Well, this is exactly the case for block style variations! Make sure the block is selected and take a look in the inspector panel.
This is for convenience, and you can choose style variations from the location which suits you best. For example, on larger screens, you may opt to change block styles via the inspector panel as it enables you to swap between styles via a single mouse click. But when on smaller devices, you might want to hide the inspector panel and just change styles via the block toolbar instead.
Core Block Support
A few core blocks currently support block style variations, including:
- Button
- Pull Quote
- Quote
- Separator
- Table
I’m sure support will be added for other core blocks in the future as this feature becomes more widely adopted. It’s so flexible I’m sure a lot of users will come to expect a selection of predefined style options for most blocks. Once you’ve used block style variations, it’s easy to see why this could be the case.
You can add block style variations to your own blocks too, of course. We’ll explore the specific implementation details next.
Implementing Block Style Variations
There are two methods for implementing custom block style variations. If you have access to the block definition then you can specify block style variations directly inside the registerBlockType() function via the style property.
For example, this is what the button core block styles property definition looks like.
styles: [
{ name: 'default', label: _x( 'Rounded', 'block style' ), isDefault: true },
{ name: 'outline', label: __( 'Outline' ) },
{ name: 'squared', label: _x( 'Squared', 'block style' ) },
],
Here, three new block style variations are registered. Notice that the Rounded style is also set as the default.
However, if you don’t have access to the block source code then there’s another approach you can take. In Gutenberg 3.4, two new functions were added to register and unregister block style variations from outside of the block definition.
To register a custom block style variation, use the registerBlockStyle() function as follows:
wp.blocks.registerBlockStyle( 'core/button', {
name: 'custom-button-style',
label: 'My Button Style'
} );
This adds a new block style variation named custom-button-style to the core button block. Now, when a button block is inserted into the editor, you’ll see the new block style variation available.
As soon as it’s selected, the block style variation adds an is-style-custom-button-style CSS class to the Additional CSS Class text field in the block inspector panel.
This in turn triggers an update to the block output, and the class is added to the HTML markup.
You might be wondering where you add the registerBlockStyle() function in your own code. Don’t worry—we’ll be covering a full example in the next post, and you’ll be able to download the final plugin code so you can test it out yourself.
A Small Gotcha!
When you first insert a block that supports block style variations, it’s interesting to note that no CSS class is actually added to the block markup until you specifically click on a block style variation, even though one is shown as being selected by default.
Try it out for yourself.
Insert a new button block into the editor and open up the block style variation options. You should see the Rounded option selected by default. If you open up the Advanced section in the block inspector, no CSS class has been added to the text field yet. And thus no CSS class will be inserted into the blocks markup. Check out the HTML outputted for the button block in the editor to confirm for yourself.
Now go back to the block style variation settings for your button block and click the default option (the one that’s selected) or any of the other block style options. You’ll immediately see the CSS class is added to the Additional CSS Class text field and the blocks wrapper markup. Any custom CSS rules that have been defined for the custom class will also be applied as soon as the block style variation has been selected.
This behavior is a little confusing on first exposure as intuitively you’d expect the CSS class to be added automatically for the block style variation that’s selected by default.
Conclusion
We’ve learned what block style variations are and why they are a useful addition to the block editing experience. I also demonstrated a basic implementation of a block style variation.
In the next post, we’ll go through fully working examples of how to register your own block styles and hook up the CSS via a plugin, and also via a child theme.
We’ll also take a look at how to unregister block styles and how to set which style variation is selected by default when a block is first inserted into the editor.