Mastering Customized Block Types in WordPress: 6 Strategies for Theme and Plugin Builders

Block Fashion Variations (block kinds) allow builders to give content material creators pre-made styling choices for core blocks, making certain model consistency and streamlining content material manufacturing. Utilizing block kinds also can remove the necessity to create customized blocks, lowering code upkeep.

On this information, you’ll study a number of methods so as to add customized block kinds in WordPress, whether or not you’re working with a theme or a plugin. We’ll cowl choices utilizing JSON (theme.json), PHP (register_block_style()), and JavaScript, with clear steering on which methodology fits which scenario.

Additionally, you will discover ways to take away core block kinds from the editor and curate the expertise on your content material creators. 

The theme.json code refers to block kinds as “variations” (brief for “block type variations”), which is typically confused with block variations or International Types variations. This publish refers to those as “block kinds” to keep away from confusion.

This publish begins with easy examples and step by step introduces extra superior strategies for including block kinds, from fast theme tweaks to plugin-based approaches.

The code referenced on this publish can also be out there on GitHub: 

• Theme: plain-pauli
• Plugin: block-styles

You’ll need to have a fundamental understanding of CSS to comply with alongside. Being snug with theme.json can also be key, and understanding a bit about PHP and WordPress hooks will certainly turn out to be useful.

To comply with alongside or use the instance code, you should utilize Studio, our free and open supply native growth atmosphere, out there for Mac and Home windows.

1. What are customized block kinds?
2. Methodology 1: add a block type by way of a JSON file (/kinds folder) 
3. Methodology 2: register block type in PHP and magnificence it by way of theme.json
   1. Register block type 
   2. Add styling to theme.json
4. Methodology 3: add a block type with register_block_style() (PHP)
   1. 3a. Use the style_data parameter
   2. 3b. Use the inline_style parameter
   3. 3c. Use the style_handle parameter
5. Methodology 4: register block kinds utilizing JavaScript + CSS
6. Optionally available: eradicating undesirable core block kinds
7. Abstract: customized block kinds at a look
8. Assets to study extra

What are customized block kinds?

Customized block kinds allow you to outline different visible therapies for present blocks, like including a border, altering the background, or tweaking typography. 

When the block is chosen, these customized kinds will seem within the Types panel inside the editor sidebar, giving content material creators simple methods to use constant, reusable design patterns. You possibly can create as many customized block kinds as you’d like.

Beneath you’ll discover an instance of the Picture block. The Types panel beneath reveals 4 kinds: Default, Rounded, Purple Border, and Crimson Border (which is the chosen type displaying within the editor).

We’ll stroll by means of six methods so as to add customized block kinds in WordPress, from easy theme edits to extra superior strategies.

Methodology 1: add a block type by way of a JSON file (/kinds folder) 

• Greatest for: Theme builders
• The place you’d usually use it: Generally in themes 
• Model necessities: WordPress 6.6 or increased with theme.json v3 

For theme builders, essentially the most streamlined means so as to add customized block kinds to a theme is so as to add a brand new file to the /kinds folder. 

This methodology requires upgrading the theme.json schema to v3, which is barely out there in WordPress 6.6 and above. As a theme developer, you’d both require your customers to put in the Gutenberg plugin or replace the minimal requirement on your theme to WordPress 6.6 to make sure every little thing works as meant.

Say we wished so as to add a blue border type referred to as image-blue-border.json.

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"model": 3,
	"title": "Blue Border",
	"slug": "blue-border",
	"blockTypes": [ "core/image" ],
	"kinds": {
            "border": {
                    "coloration": "#00f9ff",
                    "type": "stable",
                    "width": "4px",
                    "radius": "15px"
                },
			"shadow": "var(--wp--preset--shadow--natural)"
		}
}

With theme.json v3, the metadata data for a block’s type is routinely registered inside the WP_Block_Styles_Registry:

• The title is similar because the label from the register_block_style code.
• The slug is just like the identify property of the register_block_style operate.
• The blockTypes property can be utilized to assign a method to a selected block or sequence of blocks.

The code "shadow": "var(--wp--preset--shadow--natural)" refers back to the preset “Pure” shadow type in WordPress. Through the use of a preset variable, your block will routinely mirror any international type adjustments, holding your design constant throughout themes and updates.

When you save your code adjustments:

• Your new type is added to the Types panel for that individual block. 
• The block editor reveals a preview once you hover over the button.
• The Types engine attaches the CSS class is-blue-border to the block within the editor and on the frontend.
• When opening the International Types by way of Types → Blocks → Picture, the kinds might be modified by the person for the entire website. 

To arrange your block type code, you may create a subfolder within the kinds folder referred to as /blocks and hold all of them collectively. A number of theme builders discovered they might cut back the size of their features.php file significantly by implementing subfolders as a substitute.

Methodology 2: register block type in PHP and magnificence it by way of theme.json

• Greatest for: Theme builders
• The place you’d usually use it: Within the theme.json file and in features.php
• Model necessities: WordPress 6.6 or increased with theme.json v3 

So as to add a customized block type utilizing this methodology, you’ll have to register the type and add your stylings within the theme.json file.

Register block type 

In your features.php file, use the register_block_style() operate to set the 2 obligatory arguments (further optionally available arguments are lined beneath): 

• identify: The identifier of the type used to compute a CSS class.
• label: A human-readable label for the type.

As soon as set, you may add them to the init hook in your theme. 

operate my_style_red(){

   register_block_style(
       'core/picture',
       array(
           'identify'  => 'red-border',
           'label' => __( 'Crimson Border', 'my-theme' )
       )
   );
}
add_action( 'init', 'my_style_red' );

Add styling to theme.json

We’ll add some styling for the red-border variation to the theme.json file. It’s positioned inside the kinds.blocks.core/picture part, as we’re making adjustments to the Picture block.

"kinds": {
       "blocks": {
           "core/picture":{
               "variations": {
                   "red-border":{
                       "border": {
                               "coloration":"#cf2e2e",
                               "type": "stable",
                               "width": "4px",
                               "radius":"15px"
                       }
                   }
               }
           },

These two code snippets work collectively as a result of the identify used within the register_block_style() operate in your features.php file and the variations’ identify arguments in your theme.json file are equivalent. 

This methodology produces the identical editor and frontend outcomes as utilizing a JSON file within the /kinds folder:

• The type shall be seen within the editor and on the frontend. 
• It’s also out there by way of the Editor → Types → Blocks → Picture part for international customization.

If the kinds out there in theme.json aren’t sufficient, you’ve gotten a couple of choices: 

• You should use the CSS property in JSON notation. The WordPress.org per-block CSS with theme.json article supplies a great abstract of how to do that. 
• You should use any of the strategies beneath and add them to your features.php file. 
• You possibly can register the block type by way of register_block_style() and embrace the CSS in your theme’s total type.css file, referencing the block and magnificence class identify. That being mentioned, this isn’t really useful as these kinds will all the time load, even when the block isn’t in use. A bug can also be stopping the kinds from loading on the frontend.
• You should use block stylesheets to solely load the kinds when the block is used, as outlined within the WordPress Theme handbook tutorial on block stylesheets. 

Methodology 3: add a block type with register_block_style() (PHP)

The register_block_style() operate has three further and optionally available parameters. They’re listed on the documentation web page for the WP_Block_Styles_Registry class that handles the registration and administration of block kinds.

• style_data: A theme.json-like object used to generate CSS.
• inline_style: Inline CSS code that registers the CSS class required for the type.
• style_handle: The deal with of a beforehand registered type to enqueue alongside the block type.

See the documentation for register_block_style() for extra data.

3a. Use the style_data parameter

• Greatest for: Plugin builders and theme builders
• The place you’d usually use it: In plugin information or features.php 
• Model necessities: WordPress 6.6 or increased

Though block kinds have been a elementary means that WordPress works since 5.0, the style_data parameter was added in WordPress 6.6. 

This methodology for outlining block kinds makes use of “a theme.json-like object,” which means an array of nested kinds in a format that very intently resembles the kinds part of the theme.json file. On the root degree, the kinds are utilized to the block(s) that you just outline with the block_name array. 

In case you are acquainted with theme.json construction, you should utilize this methodology so as to add further kinds. This methodology allows these kinds in Editor → Types → Blocks and customers could make adjustments there. 

As you may see, the array notation for this parameter follows JSON intently. 

The theme.json reads:

"border": {
             "coloration":"#cf2e2e",
             "type": "stable",
             "width": "4px",
             "radius":"15px"
          }

The array in PHP reads:

array(
       'border' => array(
       'coloration' => '#f5bc42',
       'type' => 'stable',
       'width' => '4px',
       'radius' => '15px'
      ),

To additional exhibit this concept, this operate provides an orange border with a field shadow utilizing the “sharp” shadow type preset. 

operate my_orange_border() {

   register_block_style(
       array( 'core/picture' ),
       array(
           'identify'         => 'orange-border',
           'label'        => __( 'Orange Border', 'pauli' ),
           'style_data'=> array(
                           'border' => array(
                           'coloration' => '#f5bc42',
                            'type' => 'stable',
                            'width' => '4px',
                            'radius' => '15px'
                           ),
                       'shadow' => array(
                           'var(--wp--preset--shadow--sharp)'
                           )
                       )

           )
   );
};

add_action( 'init', 'my_orange_border' );

Of the three parameters, solely the style_data data shall be added to the worldwide type part within the website editor and might be edited by the location proprietor. The opposite two add the kinds to the Types panel, and there’s no edit path inside the UI.

3b. Use the inline_style parameter

• Greatest for: Plugin builders and theme builders
• The place you’d usually use it: In the principle plugin PHP file or features.php
• Model necessities: WordPress 5 or increased

The worth for the inline_style parameter is a mixture of the CSS selector and the CSS properties.

operate my_double_frame_styles() {
   register_block_style(
       'core/picture',
       array(
           'identify'         => 'double-frame',
           'label'        => __( 'Double-Body', 'pauli' ),
           'inline_style' => '.wp-block-image.is-style-double-frame
                               img { border: 10px ridge lightgreen; }'
       )
   );
}
add_action( 'init', 'my_double_frame_styles' );

The category identify follows commonplace block editor naming conventions. Every core block’s class identify incorporates the prefix wp-block + the block identify, like picture. It’s then adopted by the block type prefix is-style and the registered type slug, like double-frame.

The category identify .wp-block-image.is-style-double-frame is adopted by the type that you just need to connect to the block. Right here you see the CSS values for the border property for the picture aspect (img). It provides a ridged, mild inexperienced 1px border. 

You possibly can have fairly a couple of CSS properties mixed within the inline_style parameter for the operate, however it could turn out to be onerous to learn and handle.

3c. Use the style_handle parameter

• Greatest for: Plugin builders and theme builders
• The place you’d usually use it: In plugin information or features.php
• Model necessities: WordPress 5 or increased

For extra elaborate kinds, think about inserting the CSS in a separate file and utilizing wp_enqueue_style() to load it on the frontend and backend. Then use the style_handle parameter within the register_block_style() operate. 

Right here is a few instance code utilizing this methodology so as to add a purple border type.

operate my_purple_border_styles() {
   wp_enqueue_style(
       'my-image-block-style',
       plugin_dir_url(__FILE__) . '/my-purple-border.css',
       array( 'wp-edit-blocks' ),
       '1.0'
   );
 
   register_block_style(
       'core/picture',
       array(
           'identify'         => 'purple-border',
           'label'        => __( 'Purple Border, barely rounded', 'pauli' ),
           'style_handle' => 'my-image-block-style'
       )
   );
}

And right here is the accompanying my-purple-border.css file, which is positioned into the plugin’s root folder.

.is-style-purple-border img {
   border: 6px stable purple;
   border-radius: 15px;
   box-shadow: 10px 5px 5px #e090fc;
};

The picture block now has a purple border with a pinkish shadow type. 

Notice: There’s additionally a bug report open in regards to the stylesheet loading even when the block kinds aren’t used. Due to this, it’s not really useful for complicated CSS.

Methodology 4: register block kinds utilizing JavaScript + CSS

• Greatest for: Plugin builders and theme builders
• The place you’d usually use it: In a separate *.js file, enqueued in a plugin file, or in features.php
• Model necessities: WordPress 5 or increased

In comparison with utilizing the separate JSON file so as to add a block type variation, utilizing JavaScript is extra elaborate. It has three elements: 

• PHP: To enqueue the mandatory information
• JavaScript: To register the block type
• CSS: To type the block

The wp_enqueue_script() operate provides JavaScript information to a webpage. It’s not JavaScript itself, however fairly a WordPress PHP operate that’s usually utilized in WordPress theme or plugin growth. For this instance, we are able to retailer the .js file within the theme’s /js/ subdirectory and identify it curate-core.js. 

The instance code masses our customized curate-core.js file after the mandatory WordPress block editor scripts. It’s added to the underside of the web page for higher efficiency and is hooked into enqueue_block_editor_assets so it solely masses within the editor. 

This code instance goes into the theme’s features.php file or your plugin’s *.php file. 

operate pauli_block_editor_scripts() {
       wp_enqueue_script(
           'pauli-editor',
           get_theme_file_uri( '/js/curate-core.js' ),
           array( 'wp-blocks', 'wp-dom' ),
           wp_get_theme()->get( 'Model' ), true
       );
       }
      
add_action( 'enqueue_block_editor_assets', 'pauli_block_editor_scripts' );

This code ought to go within the JavaScript file curate-core.js:

wp.domReady( operate() {
   
   wp.blocks.registerBlockStyle(
       'core/picture', {
           identify: 'black-border',
           label: 'Black Border',
       }
   );

} );

You possibly can then add our block kinds to your theme’s type.css file utilizing the routinely added class identify, is-style-black-border.

.is-style-black-border img {
   border: 15px ridge black;
}

As a result of a bug, you’ll want to add the type.css to the frontend. It doesn’t appear to be routinely loaded. You employ wp_enqueue_style() after which use the hook wp_enqueue_scripts.

You then’d add the next to your features.php or plugin file:

operate enqueue_theme_styles() {
   wp_enqueue_style(
       'my-theme-styles',
       get_stylesheet_uri(), // This will get your type.css
       array(),
       wp_get_theme()->get( 'Model' )
   );
}
add_action( 'wp_enqueue_scripts', 'enqueue_theme_styles' );

You additionally want so as to add type.css to the block editor so your customers can see how the block type seems when they’re engaged on the publish or web page. 

//add type.css to editor
operate add_theme_editor_styles() {
   add_editor_style( 'type.css' );
}
add_action( 'after_setup_theme', 'add_theme_editor_styles' );

Optionally available: eradicating undesirable core block kinds

Now that you understand how to add block kinds to your theme or your plugin, you may also need to take away some further block kinds that include the block editor out of the field.

There are two features you’ll want to handle: 

• The PHP operate unregister_block_style()
• The JavaScript operate unregisterBlockStyle()

Block kinds can solely be unregistered in the identical coding language used to register them. All core blocks are registered with JavaScript. 

The instance code beneath removes the extra block type for the picture block referred to as rounded.

wp.domReady( operate() {
   wp.blocks.unregisterBlockStyle( 'core/picture', [ 'rounded' ] );
} );

For extra methods to change the block editor, learn 15 methods to curate the WordPress enhancing expertise.

Abstract: customized block kinds at a look

You now know the six methods to register block kinds for the WordPress block editor. Right here’s a fast recap of what we lined:

Block Fashion Added in Instance Code	Language	Theme/Plugin	Parameter	File	International Types
Crimson	PHP+	Theme		theme.json	sure
Blue	JSON	Theme		image-blue-border.json	sure
Orange	PHP	Theme/Plugin	style_data		sure
Purple	PHP	Theme/Plugin	style_handle	.css	no
Double Body	PHP	Theme/Plugin	inline_style		no
Black	JS	Theme/Plugin		.js + .css + .php	no

The best methodology is so as to add a JSON file to the /kinds folder utilizing the theme.json format. Another choice makes use of minimal PHP in your features.php file alongside your theme.json configuration. Each approaches add block kinds to the Types panel within the editor, the place customers can apply and customise them.

Plugin builders can use the style_data parameter to attain related outcomes, together with integration with International Types.

Different plugin-based strategies—utilizing inline_style, style_handle, or JavaScript—don’t help International Types enhancing, however nonetheless make the kinds selectable within the editor.

Remember that the primary three strategies (JSON file, theme.json with PHP, and style_data) require WordPress 6.6 or increased. To help older WordPress variations, you’ll want to make use of one of many different out there approaches.

Assets to study extra

Need to study much more about block kinds and block variations? Listed below are some assets to take a look at: 

YouTube

• Builder Fundamentals: Block Types vs. Block Variations

Make.WordPress Dev Notice

• Part kinds coming to WordPress 6.6

WordPress Developer Weblog

• Styling sections, nested components, and extra with Block Fashion Variations in WordPress 6.6
• Leveraging theme.json and per-block kinds for extra performant themes
• Per-block CSS with theme.json
• Past block kinds, half 1: utilizing the WordPress scripts bundle with themes
• Past block kinds, half 2: constructing a customized type for the Separator block
• Past block kinds, half 3: constructing customized design instruments

Block Editor Handbook

• Block Types

Themes Handbook 

• Block Fashion Variations