register_block_type()
Registers a block type.
No Hooks.
Return
WP_Block_Type|false
. The registered block type on success, or false on failure.
Usage
register_block_type( $block_type, $args );
- $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)
- Array of block type arguments. Accepts any public property of WP_Block_Type. See WP_Block_Type::__construct() for information on accepted arguments.
Default: empty array
Examples
#1 Register a new block type with additional parameters
This example shows how to register a block in a class context. The block will output the posts.
new Gutenberg_Block_Example(); // initialize class Gutenberg_Block_Example { public function __construct() { add_action( 'init', [ $this, 'gutenberg_block_register_block' ] ); add_action( 'enqueue_block_editor_assets', [ $this, 'gutenberg_block_editor_scripts' ] ); } public function gutenberg_block_register_block() { register_block_type( 'gutenberg-block/example', [ 'render_callback' => [ $this, 'gutenberg_block_render_callback' ], 'attributes' => [ 'posts_per_page' => [ 'type' => 'number', 'default' => 3, ], 'order' => [ 'type' => 'string', 'default' => 'desc', ], ], ] ); } public function gutenberg_block_editor_scripts() { wp_register_script( 'example', plugins_url( 'build/index.js', __FILE__ ), ['wp-blocks'] ); wp_enqueue_script( 'example' ); } public function gutenberg_block_render_callback( $attributes, $content ) { $args = [ 'posts_per_page' => $attributes['postsPerPage'], 'post_status' => 'publish', 'order' => $attributes['order'], ]; $posts = get_posts( $args ); $html = '<div>'; if ( $posts ) { $html .= '<ul>'; foreach ( $posts as $item ) { $html .= '<li><a href="' . get_the_permalink( $item->ID ) . '">' . $item->post_title . '</a></li>'; } $html .= '</ul>'; } else { $html .= '<h3>' . __( 'No posts!', 'gutenberg-blocks' ) . '</h3>'; } $html .= '</div>'; return $html; } }
#2 Register a new block type without additional parameters
add_action( 'init', 'gutenberg_block_register_block' ); add_action( 'enqueue_block_editor_assets', 'gutenberg_block_editor_scripts' ); // Register the new side type function gutenberg_block_register_block() { register_block_type( 'gutenberg-block/example', [] ); } // Register the main script for the block function gutenberg_block_editor_scripts() { wp_register_script( 'example', plugins_url( 'build/index.js', __FILE__ ), ['wp-blocks'] ); wp_enqueue_script( 'example' ); }
#3 Pass custom $attributes
You can pass your attributes $attributes, which can be used both in the editor and on the 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', ], ] ], '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', ] );
Important (tested in 5.0.3): It is mandatory to specify the parameter type, otherwise a notice will be issued.
#4 Autocreation of blocks via .json files
class My_Blocks { public function setup_hooks(): void { add_action( 'acf/init', [ $this, 'register_blocks' ] ); add_filter( 'block_categories_all', [ $this, 'register_block_category' ] ); } public function register_blocks(): void { $blocks = glob( __DIR__ . '/Blocks/*/block.json'); if ( ! $blocks ) { return; } foreach ( $blocks as $block ) { register_block_type( $block ); } } } ( new My_Blocks() )->setup_hooks();
Example .json file:
{ "name": "ice-cream/slider", "title": "Ice Cream Slider", { "description": "Simple customizable image slider", "style": "block.css", "category": "ice-cream", "icon": "images-alt", "apiVersion": 2, "keywords": [], "acf": { "mode": "preview", "renderTemplate": "render.php" }, "styles": [], "supports": { "align": false, "anchor": false, "alignContent": false, "color": { "text": false, "background": true, "link": false }, "alignText": false, "fullHeight": false } }
Read more here: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/
#5 Using dashicon for the block
To do this, specify an icon without the prefix dashicons-
in $args in the parameter icon
:
add_action( 'init', 'wpkama_register_block' ); function wpkama_register_block(){ register_block_type( __DIR__ . '/build.json', [ 'icon' => 'admin-home', /* omit 'dashicons-' prefix */ ] ); }
All Dashicons names: https://developer.wordpress.org/resource/dashicons/
Changelog
Since 5.0.0 | Introduced. |
Since 5.8.0 | First parameter now accepts a path to the block.json file. |
register_block_type() register block type code WP 6.4.3
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 ); }