Block Styles

What are Block Styles

Block style variations (block styles, for short) allow alternative styles to be applied to existing individual blocks. They work by adding a className to the block’s wrapper. This className can be used to provide an alternative styling for the block if the block style is selected. See the Use styles and stylesheets for a full example on how to apply styles to a block.

Many features, unfortunately, use the term “variations” in their name. This can be confusing at times. The biggest thing to note is that block style variations are not the same thing as global style variations and block variations. Also, these should also not be confused with block stylesheets. The two features can be used to work together, but they are not the same thing.

Under the hood, block styles are nothing more than CSS classes added to a block’s wrapping element with the name of .is-style-{name}. This allows you to add custom CSS to alter the block’s design in some way.

In this screenshot, you can see multiple block styles registered for the Image block under the Styles panel, and the core Rounded option is selected:

All that is happening here is that core WordPress and the theme have both registered block styles for the Image block, and the user has selected one of those styles. Then the CSS for that registered style is applied to a block.

Ultimately, block styles are just a standard way to add a class to a block and customize it with CSS.

When to use Block Styles

Block Styles are used to give blocks more than one fundamental look and/or layout. Additionally variations in Block Styles often encompass more than styling properties beyond those which can be changed thru a block settings that are available to a given block by default (ex. Font Size, Color Palette).

Take the Quote Block for example. It doesn’t have any available font settings but does have two Block Styles, Default and Large:

Limits of Block Styles

Users can only apply one style to a block at a time.

How to Register a Block Style

There are two methods of registering a new Block Style:

• Via PHP, using the register_block_style() function. Prior to WP 6.6 styles can only be registered to one block at a time.
• Via JavaScript, using the registerBlockStyle() function.

PHP seems to be the WordPress’ preferred approach to registering block styles. However, support for the is_default property seems to be spotty and may be dropped in future versions.

Add your styles in /includes/blocks/block-styles.php

How to Unregister a Block Style

Like registering a Block Style, there are two methods of removing (or unregistering) a Block Style:

• To unregister a block style that has been registered with PHP, use the unregister_block_style() function. This only works on styles that have been registered with PHP.
• There is also an unregisterBlockStyle() JavaScript function. You can use this to unregister any block styles that have been registered via JavaScript. NOTE: To avoid a race condition where there’s a conflict between when a block style is registered versus when it is unregistered, you need to ensure that you unregister a block style after it has already been registered. The best way to do this is to add it inside a function callback on wp.domReady, which ensures that you unregister after the DOM has loaded.

Refer to this list of core WordPress blocks for the block name and styles. You can also determine the name of a style using the inspector tool in your browser and looking at the values in the Default Style dropdown in the Inspector Controls.

Unfortunately, there does not seem to be an easy way to determine if a Block Style was registered via PHP or JavaScript.

JavaScript is generally preferred over PHP to remove Block Styles because it can remove block styles registered client-side, which is often the case for core WordPress block styles. The PHP function only works for server-side registered styles, making it less versatile in most scenarios.

Remove your styles in /src/blocks/block-styles.js – be sure to rebuild your scripts after updating.

Where to put your CSS for a block style

Styles for a block can live in several places depending on if the block is coming from a plugin, or if the block is part of a theme.

• For Blocks added from plugins, you’ll want to add them under the .../src/scss/plugins/ directory of a theme. For example The Styles for the BU-Blocks Lead-In Block live in .../src/scss/plugins/bu-blocks/blocks/_block-leadin.scss which is then compiled into theme.css
• Blocks built in the them are compiled seperately with their own styles. Thus the styles for those blocks would live in .../src/blocks/(blockname)/block-base.scss

Using Block Styles with other customizations in Edit.js or Render.php

The contents and function of a Block can be made to vary by Block Styles thru the use of its edit.js and render.php. With that said it’s advised that blocks not do so and instead retain the same behavior across all its style variations unless absolutely necessary. Tying potions of content or functionality of a block behind different styles can make the block more convoluted and less performant for users. Block Styles are understood to provide visual variety in a block, and styling functionality to this could cause confusion for those working with a given block.

The Lead-In Block for BU Blocks is an example that changes its content based on Block Styles. For example the placement.

On line 120 and 125 of its php file theres a series of if() statements that change where the caption text is rendered based on the styles chosen https://github.com/bu-ist/bu-blocks/blob/415b7805412769373a354fcee195ae8052184e95/src/blocks/leadin/index.php#L120

Additionally there are several options that are only present for certain Block Styles such as Text Position controls for the Image with Text Overlay style. https://github.com/bu-ist/bu-blocks/blob/415b7805412769373a354fcee195ae8052184e95/src/blocks/leadin/leadin.js#L257

Further Reading

• WordPress: Block API: Styles
• WordPress: Block Style Variations
• 10up: Block Styles