Custom block styles

Level: Beginner, developer

Estimated reading time: 3 minutes

Custom block styles with the register_block_style function, are available in WordPress since version 5.3.0 and does not require the Gutenberg plugin to be installed or full site editing to be enabled.


Custom block styles is about adding new styles to existing blocks.
The difference between just styling a block, and adding a custom block style is that ultimately, it is the user who decides if they want to use the style or not.

The styles are optional, and can be previewed and selected in the block panel.
Custom block styles are often simplistic, but can be impactful. It can be a text shadow, or a border around a paragraph block.

Perhaps you want to be able to use a larger button, or rounded corners on your group block. If you want, you can create multiple styles for the same block.

When a user selects a custom block style, there are no additional settings.

[ Screen: In the WordPress block editor, a block with a border is selected ]

For example, with the custom block style, you won’t be able to adjust the thickness of the border. If you wanted a 3 pixel border, and a 10 pixel border, you would need two styles.

I recommend that you select your styles carefully. Because more options does not make it easier for the user to create a beautiful site. It is easy to go overboard here.

How to create custom block styles

You create the custom block style with the PHP function register_block_style.

register_block_style( string $block_name, array $style_properties )

(string) (Required) 
Block type name including namespace.

(array) (Required) 
Array containing the properties of the 
style name, 
style (name of the stylesheet to be enqueued),
inline_style (string containing the CSS to be added).

First, we need to tell the function which block we want to style. In this example, I am using the core paragraph block.

        'name'  => 'prefix-rounded-corners',
	'label' => __( 'Rounded corners (Requires background color)', 'textdomain' ),
        'inline_style' => '.is-style-prefix-rounded-corners {  
	   border-radius: 6px;


The second argument is an array, where you will add the name, which is the CSS class that identifies your style, and the label, which is the visible name in the block panel.

Then you have a decision to make about where you want your CSS to be.

You can use the inline style, or, you can define a style handle
for a style that you are already enqueueing.

When you choose the inline CSS option, you will add all your code as a value inside the array.

If your CSS is complex, you may also need to escape certain characters.

'inline_style' => ' {
 mask-image: url(\'data:image/svg+xml; utf8, <svg xmlns="" viewBox="0 0 81.52 29.9">
	<path ... /></svg>\' );

If you add the style handle, do remember, that this stylesheet needs
to be added both to the editor and on the front.

If you want to avoid your styles being overwritten by plugins,
[Narrator raises her voice: -Hi Yoast! It’s OK we forgive you.]
use your theme slug or your company name, just prefix them.

Additional notes

-Since the creation of this lesson, many blocks have added options for borders and border radius, and the examples may be redundant.
The description and the code for adding block styles is correct.

I have received questions about if it is possible to select two block styles, but as of September 2021, this is still not possible.
You can follow the discussion and progress on allowing multiple block styles here:
Gutenberg #14598