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.

Contents

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 string
    Block API version.
  • title string
    Human-readable block type label.
  • category string|null
    Block type category classification, used in search interfaces to arrange block types by category.
  • parent string[]|null
    Setting parent lets a block require that it is only available when nested within the specified blocks.
  • ancestor string[]|null
    Setting ancestor makes a block available only inside the specified block types at any position of the ancestor's block subtree.
  • icon string|null
    Block type icon.
  • description string
    A detailed block type description.
  • keywords string[]
    Additional keywords to produce block type as result in search interfaces.
  • textdomain string|null
    The translation textdomain.
  • styles array[]
    Alternative block styles.
  • variations array[]
    Block variations.
  • selectors array
    Custom CSS selectors for theme.json style generation.
  • supports array|null
    Supported features.
  • example array|null
    Structured data for the block preview.
  • render_callback callable|null
    Block type render callback.
  • attributes array|null
    Block type attributes property schemas.
  • uses_context string[]
    Context values inherited by blocks of this type.
  • provides_context string[]|null
    Context provided by blocks of this type.
  • block_hooks array[]
    Block hooks.
  • 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()

Top ↑

Return

WP_Block_Type|false The registered block type on success, or false on failure.

Top ↑

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 );
}

View on Trac View on GitHub

Top ↑

Top ↑

Changelog

Changelog
Version Description
5.8.0 First parameter now accepts a path to the block.json file.
5.0.0 Introduced.

Top ↑

User Contributed Notes

  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 7You must log in to vote on the helpfulness of this note
    Contributed by Michael Levy —

    How to write a plugin with multiple blocks:

    Setting up the src folder

    1. Take the content of the src directory created by @wordpress/create-block and place it in a sub-directory, for example block-a.
    2. Duplicate the sub-directory to make a second block and name it, for example 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 the build directory.

    The two blocks can be registered by pointing to the matching directory in the build folder.

    function wpdocs_create_blocks_mysite_block_init() {
	
	register_block_type( __DIR__ . '/build/block-a' );
	register_block_type( __DIR__ . '/build/block-b' );

}
add_action( 'init', 'wpdocs_create_blocks_mysite_block_init' );
  3. Skip to note 3 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note
    Contributed by jmau —

    You can pass custom $attributes which can be used both on editor and front-end in render_callback :

    register_block_type( 'my_namespace/my_block', [
	'render_callback' => 'render_callback',
	'attributes'      => [
		'some_string' => [
			'default' => 'default string',
			'type'    => 'string'
		],
		'some_array'  => [
			'type'  => 'array',
			'items' => [
				'type' => 'string',
			],
		]
	]
] );

    Important (tested in 5.0.3) : in case of array attributes you MUST specify items type. Otherwise it would trigger a notice.

  4. Skip to note 4 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note
    Contributed by Carlos —

    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.

  5. Skip to note 5 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note
    Contributed by Shah Alom —

    Here is an example snippet that I use for one of my own projects

    function mcqa_register_block_related_quiz() {
    if ( ! function_exists( 'register_block_type' ) ) {
        // Block editor is not available.
        return;
    }

    register_block_type( 'mcqac/related-quiz', array(
        'editor_script' => 'mcqac-related-quiz-block-script',
        'editor_style'  => 'mcqac-related-quiz-block-editor-style',
        'style'         => 'mcqac-related-quiz-block-frontend-style',
    ) );
}

// Hook: Editor assets.
add_action( 'init', 'mcqa_register_block_related_quiz' );
  6. Skip to note 6 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note
    Contributed by BigupJeff —

    If you wish to set a dashicon in the args, you must omit the dashicons- prefix:

    register_block_type(
	__DIR__ . '/build',
	array(
		'icon' => 'admin-home', /* omit '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.

  7. Skip to note 7 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
    Contributed by livemesh —

    The arguments to register_block_type() function match the instance vars of WP_Block_Type class, i.e., attributes, render_callback, editor_script, editor_style, script and style. 

            register_block_type(
            'my-custom-blocks/calendar',
            array(
                'attributes' => array(
                    'align' => array(
                        'type' => 'string',
                        'enum' => array( 'left', 'center', 'right', 'wide', 'full' ),
                    ),
                    'day' => array(
                        'type' => 'integer',
                    ),
                    'month' => array(
                        'type' => 'integer',
                    ),
                    'year' => array(
                        'type' => 'integer',
                    ),
                ),
                'render_callback' => 'render_block_my_custom_blocks_calendar',
                'editor_script'   => 'calendar-editor-js',
                'editor_style'    => 'calendar-editor-css',
                'script'          => 'calendar-frontend-js',
                'style'           => 'calendar-frontend-css',

            )
        );

    This is because the register_block_type() function utilizes the name and arguments provided in the function call to create a new instance of WP_Block_Type class and the instance thus created is registered with the global WP_Block_Type_Registry instance.

  9. Skip to note 9 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by markshall —

    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.

    function wpdocs_register_multiple_blocks() {
	$build_dir = __DIR__ . '/build';

	foreach ( scandir( $build_dir ) as $result ) {
		$block_location = $build_dir . '/' . $result;

		if ( ! is_dir( $block_location ) || '.' === $result || '..' === $result ) {
			continue;
		}

		register_block_type( $block_location );
	}
}

add_action( 'init', 'wpdocs_register_multiple_blocks' );

You must log in before being able to contribute a note or feedback.