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:

WordPress post editor showing an Image block with a rounded style in the content canvas.

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:

By default presents the quote shifted slightly to the right with a border on the left hand side

– Lorem ipsum dolor

In contrast the Large Quote Style does away with the left hand border and padding, and uses a larger font size.

– Lorem ipsum dolor

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

@todo

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

@todo

Further Reading