Add Custom Block Styles in WordPress: register_block_style and Removal

This article is a localized edition of the Japanese original. Read the Japanese original

Block styles let editors pick a visual variation of a block from the Styles section of the block settings sidebar. Choosing a style adds the class is-style-stylename to the block's outermost element. If you write CSS for that class, editors can switch the look without knowing any class names.

The behavior of the functions and hooks in this article was checked against the WordPress core source code (6.9) and the Block Editor Handbook.

Styles that core blocks already have

Some core blocks come with styles already registered. Registering a style with the same name causes a clash, so give your own styles different names. These are the style names in each block's block.json in WordPress 6.9.

An outline-only button (outline) and rounded images (rounded) are available without registering anything.

Register a style with register_block_style

In your theme's functions.php (or a plugin), call register_block_style() inside the init hook. The first argument is the block name and the second is the style settings.

If you pass the CSS with inline_style, WordPress loads it both on the front end and in the block editor. For a small amount of CSS this is the easiest way.

<?php
// functions.php
add_action( 'init', function () {
	// Button: shadow
	register_block_style( 'core/button', array(
		'name'         => 'shadow',
		'label'        => 'Shadow',
		'inline_style' => '.wp-block-button.is-style-shadow .wp-block-button__link { box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2); }',
	) );

	// Quote: thick left border
	register_block_style( 'core/quote', array(
		'name'         => 'bordered',
		'label'        => 'Left border',
		'inline_style' => '.wp-block-quote.is-style-bordered { border-left: 4px solid currentColor; padding-left: 1.5rem; font-style: normal; }',
	) );

	// Group: card
	register_block_style( 'core/group', array(
		'name'         => 'card',
		'label'        => 'Card',
		'inline_style' => '.wp-block-group.is-style-card { background: #fff; border: 1px solid #dcdcdc; border-radius: 8px; box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08); padding: 2rem; }',
	) );

	// Image: circle
	register_block_style( 'core/image', array(
		'name'         => 'circle',
		'label'        => 'Circle',
		'inline_style' => '.wp-block-image.is-style-circle img { border-radius: 50%; aspect-ratio: 1; object-fit: cover; }',
	) );
} );

After saving, select a block such as a button in the post editor and check that your style appears under Styles in the sidebar and that choosing it changes the look.

Since WordPress 6.6, you can pass an array of block names as the first argument to register the same style for several blocks at once.

<?php
add_action( 'init', function () {
	register_block_style( array( 'core/group', 'core/columns' ), array(
		'name'         => 'boxed',
		'label'        => 'Boxed',
		'inline_style' => '.is-style-boxed { border: 1px solid #dcdcdc; padding: 1.5rem; }',
	) );
} );

Put the CSS in a file (style_handle)

When the CSS gets longer, move it to a file, register it with wp_register_style() and pass the handle as style_handle. It is still loaded both on the front end and in the editor.

<?php
add_action( 'init', function () {
	wp_register_style(
		'mytheme-block-styles',
		get_theme_file_uri( 'assets/css/block-styles.css' ),
		array(),
		wp_get_theme()->get( 'Version' )
	);

	register_block_style( 'core/button', array(
		'name'         => 'shadow',
		'label'        => 'Shadow',
		'style_handle' => 'mytheme-block-styles',
	) );
} );

/* assets/css/block-styles.css */
.wp-block-button.is-style-shadow .wp-block-button__link {
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
  transition: box-shadow 0.2s ease, transform 0.2s ease;
}

.wp-block-button.is-style-shadow .wp-block-button__link:hover {
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.25);
  transform: translateY(-2px);
}

The is-style-{name} class goes on the block's outermost element. For the button block that is the outer div.wp-block-button, and the actual button is the .wp-block-button__link inside it. Check the real HTML in your browser's developer tools when writing selectors.

You can also load a per-block stylesheet with wp_enqueue_block_style() (WordPress 5.9 and later). On sites that load block styles on demand (such as block themes), the CSS is loaded only on pages where that block is displayed.

Remove styles

Remove styles registered in PHP

unregister_block_style() only removes styles registered with PHP's register_block_style(). To remove a style that a plugin or parent theme registered in PHP, call it after that style is registered (for example, at a later init priority).

<?php
add_action( 'init', function () {
	unregister_block_style( 'core/button', 'shadow' );
}, 20 );

Remove core styles (JavaScript)

Styles that core blocks have out of the box (such as the quote block's plain) are defined in block.json, so PHP's unregister_block_style() cannot remove them. Use JavaScript's wp.blocks.unregisterBlockStyle() instead. To avoid ordering problems with registration, the Handbook runs it inside wp.domReady() and lists wp-blocks, wp-dom-ready and wp-edit-post as dependencies.

// assets/js/block-styles.js
wp.domReady( function () {
	// Remove the quote block's "plain" style
	wp.blocks.unregisterBlockStyle( 'core/quote', 'plain' );

	// Remove the separator block's "dots" style
	wp.blocks.unregisterBlockStyle( 'core/separator', 'dots' );
} );

<?php
add_action( 'enqueue_block_editor_assets', function () {
	wp_enqueue_script(
		'mytheme-block-styles',
		get_theme_file_uri( 'assets/js/block-styles.js' ),
		array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' ),
		wp_get_theme()->get( 'Version' ),
		true
	);
} );

This file is loaded as is, without a build step, so it uses the global wp.blocks instead of import statements. If you write import { registerBlockStyle } from '@wordpress/blocks';, build the file with @wordpress/scripts or similar before loading it.

You can also add styles in JavaScript with wp.blocks.registerBlockStyle(), but unlike PHP's register_block_style(), you have to load the CSS separately.

Things to watch out for

• Removing a style does not remove the is-style-… class from blocks that already use it. If you delete the CSS, those blocks will look different.
• Renaming a style later breaks the match with the class names on blocks that already use it. Do not change style names after publishing.
• Only one block style can be selected per block. For combined looks, put them into a single style or use the block's color and spacing settings.

How to make the block editor match your front end is covered in Set up editor styles (editor-style.css) in WordPress.

Summary

• Calling register_block_style( 'block-name', array( 'name' => …, 'label' => …, 'inline_style' => … ) ) on init adds an option to the Styles section and the is-style-{name} class
• CSS passed with inline_style or style_handle loads on both the front end and in the editor
• Choose names that do not clash with core names such as outline or rounded
• Remove PHP-registered styles with unregister_block_style() and core styles with wp.blocks.unregisterBlockStyle()

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)