register_block_style() │ WP 5.3.0

Registers a new style (style variation) for a block/blocks.

The function adds a style variation with a name (slug) and label. When the variation is selected, a class of the form .is-style-{name} is applied to the block wrapper, and CSS can be enqueued beforehand, added inline, or generated from style_data.

The created stylistic variant (style variation) can be selected by the user in the styles panel — this will apply the corresponding CSS class to the selected block. Also, this variation can be styled in the FSE editor.

You can register a style for several blocks at once by passing an array of block names (supported in newer versions).

It is recommended to register styles on the init hook.

No Hooks.

Returns

true|false.

  • true on successful registration of the style
  • false on failure.

Usage

register_block_style( $block_name, $style_properties );
$block_name(string|array)
Block name in the format namespace/block or an array of such names for which the style is being registered.
$style_properties(array)

Style properties. See WP_Block_Styles_Registry::register():

  • name (string) — Required. Unique slug of the style variation, forms the CSS class .is-style-{name}.

  • label (string) — Required. Label (name) for the editor UI.

  • style_handle (string) — handle (id) of a previously registered style to enqueue. See: wp_register_style().

  • inline_style (string) — CSS added inline for this style.

  • style_data (array) — data in theme.json format from which CSS will be generated.

Default: []

Examples

1

#1 Demo

We register a style for core/paragraph with a label and a slug; CSS will be enqueued separately.

add_action( 'init', 'myplugin_register_block_styles' );

function myplugin_register_block_styles() {
	register_block_style(
		'core/paragraph',
		[
			'name'  => 'lead',
			'label' => __( 'Lead paragraph', 'myplugin' ),
		]
	);
}
0

#2 Registering a style with inline CSS

Add inline CSS for quick prototyping without a separate stylesheet.

add_action( 'init', 'myplugin_register_block_styles_inline' );

function myplugin_register_block_styles_inline() {
	register_block_style(
		'core/image',
		[
			'name'         => 'soft-shadow',
			'label'        => __( 'Soft shadow', 'myplugin' ),
			'inline_style' => '.wp-block-image.is-style-soft-shadow img{box-shadow:0 6px 20px rgba(0,0,0,.15);}',
		]
	);
}
0

#3 Register a style for multiple blocks at once

The same style will be available in several blocks at once.

add_action( 'init', 'myplugin_register_multi_block_style' );

function myplugin_register_multi_block_style() {
	register_block_style(
		[ 
			'core/group', 
			'core/cover' 
		],
		[
			'name'  => 'wide-padding',
			'label' => __( 'Wide padding', 'myplugin' ),
		]
	);
}
0

#4 Registration using style_handle

Connect a previously registered style to avoid duplicating CSS.

add_action( 'init', 'myplugin_register_block_style_with_handle' );

function myplugin_register_block_style_with_handle() {
	wp_register_style(
		'myplugin-block-styles',
		get_stylesheet_directory_uri() . '/assets/css/block-styles.css',
		[],
		wp_get_theme()->get( 'Version' )
	);

	register_block_style(
		'core/list',
		[
			'name'         => 'check',
			'label'        => __( 'Check list', 'myplugin' ),
			'style_handle' => 'myplugin-block-styles',
		]
	);
}
0

#5 Registration via style_data (CSS generation)

We use style_data so WordPress will generate CSS from "theme.json‑like" data.

add_action( 'init', 'myplugin_register_block_style_data' );

function myplugin_register_block_style_data() {
	register_block_style(
		'core/group',
		[
			'name'       => 'green-bg',
			'label'      => __( 'Green background', 'myplugin' ),
			'style_data' => [
				'color' => [
					'background' => 'green',
				],
				'spacing' => [
					'padding' => [
						'top'    => '1.5rem',
						'right'  => '1.5rem',
						'bottom' => '1.5rem',
						'left'   => '1.5rem',
					],
				],
			],
		]
	);
}

Changelog

Since 5.3.0 Introduced.
Since 6.6.0 Added support for registering styles for multiple block types.

register_block_style() code WP 6.9

wp-includes/blocks.php 
function register_block_style( $block_name, $style_properties ) {
	return WP_Block_Styles_Registry::get_instance()->register( $block_name, $style_properties );
}

Gutenberg (blocks editor)

Block Editor (Gutenberg)