How to add a custom block style in a WordPress block theme

Block styles are the options under “Styles” in the block settings, like “Rounded” on the Image block and “Outline” on the Button block. Pick one, and WordPress adds a class to the block that changes how it looks. Themes can add their own, and I’m yet to build a block theme that didn’t require one or several custom block styles. For this site, which customizes the WordPress default styles heavily, they number in the dozens.

In this tutorial, we’ll add a “Checklist” style to the List block, which swaps the bullets for checkmarks. It’s a common sight on landing pages and pricing tables, common enough that Twenty Twenty-Five ships a “Checkmark” style of its own. Ours colors the checkmarks, and gets a different name so the two don’t get mixed up if you follow along in Twenty Twenty-Five.

There are two ways to add a block style: with a JSON file in the theme, or with a few lines of PHP. We’ll go through both, and then how to remove a core block style you don’t want.

Adding a block style with a JSON file

Since WordPress 6.6, themes can add block styles with JSON files in the styles folder, the same folder that holds the theme’s style variations. What makes a file a block style is the blockTypes property, which lists the blocks the style is for. Twenty Twenty-Five uses this for the “Style 1” to “Style 5” options on the Group block, which you can find in its styles/sections folder. Ipsum, the new default theme coming in WordPress 7.2, keeps its block styles in a styles/blocks folder, which is the setup we’ll use here.

Create a file called checklist.json in your theme’s styles folder. I’ve put mine in a blocks subfolder, to keep it apart from the style variations, but WordPress finds it in any subfolder.

{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"title": "Checklist",
"slug": "checklist",
"blockTypes": [ "core/list" ],
"styles": {
"css": "& { list-style-type: \"✓\"; } & li { padding-inline-start: 1ch; } & li::marker { color: var(--wp--preset--color--accent-3); font-weight: 700; }"
}
}
  • title is the name shown in the editor, and slug is used in the class WordPress adds to the block, is-style-checklist.
  • blockTypes lists the blocks the style shows up on. You can add more than one.
  • styles takes the same settings as the styles section of theme.json, like colors, spacing and borders. There are no settings for list markers, though, so the checkmarks go in css, which takes plain CSS. The & stands for the block itself, so & li targets the list items inside it.
  • The color is the accent-3 preset from Twenty Twenty-Five, so swap it for one of your theme’s colors.

Adding a block style with PHP

If you’d rather keep it in PHP, or you’re adding the style from a plugin, register_block_style() does the same thing. Since 6.6, it takes a style_data argument with the same styles as the JSON file, written as a PHP array. Add this to your theme’s functions.php:

add_action(
'init',
function () {
register_block_style(
'core/list',
array(
'name' => 'checklist',
'label' => __( 'Checklist', 'your-theme' ),
'style_data' => array(
'css' => '& { list-style-type: "✓"; } & li { padding-inline-start: 1ch; } & li::marker { color: var(--wp--preset--color--accent-3); font-weight: 700; }',
),
)
);
}
);

The result is the same as with the JSON file: a “Checklist” option on the List block, with the same CSS. To add the style to more than one block, pass an array of block names as the first argument.

Before 6.6, block styles registered in PHP had to bring their own CSS, with the inline_style or style_handle arguments. That still works, and it’s how Twenty Twenty-Five adds its “Checkmark” style. But styles added that way don’t show up under “Styles” in the Site Editor, where you can change a block style without touching the code (more on that below), so I’d go with style_data.

Using the block style

Select a List block in the editor, and open the “Styles” tab in the block settings, the one with the half-filled circle icon. You’ll find “Checklist” under “Styles”, next to “Default”. Click it, and the bullets turn into checkmarks.

You can also change the style for the whole site without touching the code. In the Site Editor, go to “Styles” → “Blocks” → “List”, and you’ll find “Checklist” under “Style variations”. Changes you make there are saved in the database, and apply to every List block that uses the style.

Removing a core block style

The block styles that come with WordPress, like “Rounded” on the Image block, are registered in JavaScript. That means unregister_block_style() in PHP can’t remove them, since it only works on styles registered with PHP. To remove one, you need a small script in the editor. Add this to functions.php:

add_action(
'enqueue_block_editor_assets',
function () {
wp_enqueue_script(
'your-theme-editor',
get_theme_file_uri( 'assets/js/editor.js' ),
array( 'wp-blocks', 'wp-dom-ready' ),
wp_get_theme()->get( 'Version' ),
true
);
}
);

Then create assets/js/editor.js in the theme, with one line for each style you want to remove:

wp.domReady( () => {
wp.blocks.unregisterBlockStyle( 'core/image', 'rounded' );
} );

This only removes the option from the editor. Blocks that already use the style keep it, so you won’t break any existing content.

Notes

  • Which one to use. If you’re building a theme, I’d go with the JSON files, since they keep the block styles with the rest of the theme’s design. PHP is the way to go if the style comes from a plugin.
  • Pick a slug you’ll keep. The slug ends up in the class name of every block that uses the style. If you change it later, those blocks lose their styling until you select the style again.
  • One style per block. A block can only use one block style at a time, so a List block can be a “Checklist” or a “Checkmark”, but not both.
  • Block styles belong to the theme. If you switch themes, blocks that use the style keep the class, but lose the styling.
  • Using a theme you didn’t make? Add the files in a child theme, so they aren’t lost the next time the theme updates. A JSON file in the child theme with the same name as one in the parent theme replaces it, so you can also use that to change one of the parent theme’s block styles.