register_block_type( string|WP_Block_Type $block_type, array $args = array() ): WP_Block_Type|false
Registers a block type. The recommended way is to register a block type using the metadata stored in the block.json
file.
Parameters
-
$block_type
string|WP_Block_Type Required -
Block type name including namespace, or alternatively a path to the JSON file with metadata definition for the block, or a path to the folder where the
block.json
file is located, or a complete WP_Block_Type instance.
In case a WP_Block_Type is provided, the $args parameter will be ignored. -
$args
array Optional -
Array of block type arguments. Accepts any public property of
WP_Block_Type
. See WP_Block_Type::__construct() for information on accepted arguments.More Arguments from WP_Block_Type::__construct( ... $args )
Array or string of arguments for registering a block type. Any arguments may be defined, however the ones described below are supported by default.
api_version
stringBlock API version.title
stringHuman-readable block type label.category
string|nullBlock type category classification, used in search interfaces to arrange block types by category.parent
string[]|nullSetting parent lets a block require that it is only available when nested within the specified blocks.ancestor
string[]|nullSetting ancestor makes a block available only inside the specified block types at any position of the ancestor's block subtree.icon
string|nullBlock type icon.description
stringA detailed block type description.keywords
string[]Additional keywords to produce block type as result in search interfaces.textdomain
string|nullThe translation textdomain.styles
array[]Alternative block styles.variations
array[]Block variations.selectors
arrayCustom CSS selectors for theme.json style generation.supports
array|nullSupported features.example
array|nullStructured data for the block preview.render_callback
callable|nullBlock type render callback.attributes
array|nullBlock type attributes property schemas.uses_context
string[]Context values inherited by blocks of this type.provides_context
string[]|nullContext provided by blocks of this type.editor_script_handles
string[]Block type editor only script handles.script_handles
string[]Block type front end and editor script handles.view_script_handles
string[]Block type front end only script handles.editor_style_handles
string[]Block type editor only style handles.style_handles
string[]Block type front end and editor style handles.
Default:
array()
Return
WP_Block_Type|false The registered block type on success, or false on failure.
Source
File: wp-includes/blocks.php
.
View all references
function register_block_type( $block_type, $args = array() ) {
if ( is_string( $block_type ) && file_exists( $block_type ) ) {
return register_block_type_from_metadata( $block_type, $args );
}
return WP_Block_Type_Registry::get_instance()->register( $block_type, $args );
}
Changelog
Version | Description |
---|---|
5.8.0 | First parameter now accepts a path to the block.json file. |
5.0.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
You can load
block.json
directly:You can pass custom
$attributes
which can be used both on editor and front-end inrender_callback
:Important (tested in 5.0.3) : in case of array attributes you MUST specify items type. Otherwise it would trigger a notice.
The name of the JSON file, if provided in the
$block_type
argument, must be “block.json”. If the file does not end with such file name, WordPress will assume it is a path to that file. It seems to be up to the developer choose the file name, but it’s not.Top ↑
Feedback
I hit this problem earlier. I made a block called accordion.json. I had to rename it to accordion-block.json for it to be registered. — By Rocky Kev —
How to write a plugin with multiple blocks:
Setting up the
src
foldersrc
directory created by @wordpress/create-block and place it in a sub-directory, for exampleblock-a
.block-b
.Update the
block.json
files in each sub-directory to match the blocks’ requirements.Registering the Blocks
After running
npm run build
corresponding directories will be created in thebuild
directory.The two blocks can be registered by pointing to the matching directory in the build folder.
Here is an example snippet that I use for one of my own projects
If you wish to set a dashicon in the args, you must omit the
dashicons-
prefix:This is in contradiction to
add_menu_page()
which requires the inclusion of the prefix. These should be brought into alignment for consistency in my opinion.The arguments to
register_block_type()
function match the instance vars ofWP_Block_Type
class, i.e.,attributes, render_callback, editor_script, editor_style, script
andstyle
.This is because the
register_block_type()
function utilizes the name and arguments provided in the function call to create a new instance ofWP_Block_Type
class and the instance thus created is registered with the globalWP_Block_Type_Registry
instance.If you don’t know why it’s recommended to register a block type using metadata, read this reference https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/
To follow on from Michael Levy’s post about registering multiple blocks from the same plugin, I wrote this to automatically register any blocks generated by the
npm run build
command.