For a small project, I’ve implemented my first Block Theme (that I finished) using the Create Block Theme plugin. In the PDF with the design, there was a “round button”, which made me wonder on how I would implement it.

It seemed easy at first. Just add a button, write some text inside and set the border-radius to 50%, to make it round. The problem is: that will only work if the button has exactly the same height and width. But since you don’t know in advance what text you would use in the button, and only the width increases, the button will have an oval shape:

That doesn’t work. But how can we get the button perfectly round? We need to set the aspect-ratio for it to 1. While registering custom aspect ratios was introduced in WordPress 6.6, we cannot use it for any block. It’s currently only available for the Image, Feature Image and Cover block. How can we achieve it? That’s where Block Style Variation come into play.

What is a Block Style Variation?

As many of you know, one of the hardest things in tech is naming things, and there are many things in the “Gutenberg project” with similar names, making it all confusing. A Block Style Variation – sometimes referred to as only Block Style – is a feature that lets you create an alternative style for a block. When we think of the core/button block, we usually have the “Fill” and the “Outline” styles. The core/table block has the styles “Default” and “Striped”. WordPress Core comes with many of these block styles. But you can create your own custom ones.

Creating your own Block Style Variation

On the documentation page about Block Style Variations, you can (currently) find two different methods to register a custom block style: PHP and JavaScript. Those of you who wrote WordPress themes for some years, are probably (still) quite familiar with PHP, so let’s take a look at how to do it with PHP.

Register a Block Style with PHP

We want to have a round button, and all we have to do, is adding some PHP to our functions.php file like this:

function tt5_round_button_register_block_styles() {
	register_block_style(
		'core/button',
		[
			'name' => 'round',
			'label' => esc_attr__( 'Round', 'twentytwentyfive-round-button' ),
			'inline_style' => '.wp-block-button.is-style-round {
				aspect-ratio: 1;
				border-radius; 50%;
			}'
		]
	);
}
add_action( 'init', 'tt5_round_button_register_block_styles' );

With this code in place, we can now select the new block style from the “Style” settings in the “Block” sidebar:

Now this looks nice! And it was not really a lot of code we had to use. But it doesn’t feel right to use PHP to register a block style, when we want to create a Block Theme. So how can we do it instead? Well, we could use JavaScript, and you can find an example for that in the documentation, but I like this solution even less.

When you scroll down that page, you will find this notice:

It is not currently possible to customize your custom-registered block styles via theme.json. You can only style those registered by core WordPress at the moment.

This is really unfortunate. But it’s also not true. I’ve found a solution to register a block style and also style it using the theme.json file.

Register and customize styles for a Block Style using JSON

The feature to use custom block styles was also introduced in WordPress 6.6, and in order to use it, you need to create a new file in the styles/blocks folder of your theme. So we could create a file styles/blocks/round.json with this content:

{
  "version": 3,
  "$schema": "https://schemas.wp.org/wp/6.8/theme.json",
  "title": "Round",
  "slug": "round",
  "blockTypes": [
    "core/button"
  ],
  "styles": {
    "border": {
      "radius": "50%"
    },
    "dimensions": {
      "aspectRatio": "1"
    }
  }
}

This is really all we have to do. We can give this file any name. And we don’t have to “load” it, this is done automatically by WordPress. You should use "version: 3" here and also set the $schema to use at least “6.8” or higher (or trunk, for the latest version).

Overwriting custom Block Styles

Even though the statement says that you can’t style your custom block styles using the theme.json file, you can do it. I’ve tested it successfully in a local WordPress 6.8 installation. You could do it like this:

{
  "version": 3,
  "$schema": "https://schemas.wp.org/wp/6.8/theme.json",
  "styles": {
    "blocks": {
      "core/button": {
        "variations": {
          "round": {
            "border": {
              "color": "currentColor",
              "style": "solid",
              "width": "3px"
            },
            "color": {
              "text": "currentColor",
              "background": "white"
            }
          }
        }
      }
    }
  }
}

This would overwrite the border and colors and give us a “round outline button” that would look like this:

All of this was possible by only editing some JSON files. No need to write any “real code” in PHP or JavaScript.

Caveats

Even though we were able to create a round button without any “custom code”, the result is not perfect. We have used the dimensions.aspectRatio property for the button, but since it is not yet supported for a core/button block, we won’t be able to see and edit it in the global block styles for the theme.

Conclusion

Adding a custom block style to an existing core block can make it easier for content editors to create consistent layouts. If you want to avoid writing “real code”, you can add them using only JSON files.

If you want to learn more on that topics, I can highly recommend the page “Block style variations and section styles” on fullsiteediting.com for more examples.

I really hope that the aspectRatio and other options will be made available to other blocks as well, and also that we are able to create block styles using only the Site Editor in the future. There is already a ticket about this, but I understand that this is quite a large feature.