Registration

Block registration API reference.

You can use the functions documented on this page to register a block with JavaScript only on the client, but the recommended method is to register new block types also with PHP on the server using the `block.json` metadata file. See metadata documentation for complete information

Learn how to create your first block for the WordPress block editor. From setting up your development environment, tools, and getting comfortable with the new development model, this tutorial covers all you need to know to get started with creating blocks.

registerBlockType

Type: Function

Every block starts by registering a new block type definition. To register, you use the registerBlockType function from the wp-blocks package. The function takes two arguments, a block name and a block configuration object.

Block Name

Type: String

The name for a block is a unique string that identifies a block. Names have to be structured as namespace/block-name, where namespace is the name of your plugin or theme.

// Registering my block with a unique name
registerBlockType( 'my-plugin/book', {} );

Note: A block name can only contain lowercase alphanumeric characters and dashes, and must begin with a letter.

Note: This name is used on the comment delimiters as . Those blocks provided by core don’t include a namespace when serialized.

Important: Choose Your Namespace Carefully

Block names cannot be changed later without consequences. The block name is stored in the post content of every post using that block, so changing it requires editing all affected posts or running database scripts.

Namespace Best Practices

Use your actual plugin/theme name: my-awesome-plugin/block-name
Avoid generic names like editorial/, block/, or create-block/
Use the same namespace for all blocks in your plugin/theme
Make it unique to prevent conflicts with other plugins

// Good examples
registerBlockType( 'my-company-blocks/hero', {} );
registerBlockType( 'awesome-gallery-plugin/slideshow', {} );

// Avoid these
registerBlockType( 'create-block/example', {} ); // Too generic
registerBlockType( 'block/content', {} ); // Too generic

Note: registerBlockCollection() only works with blocks from a single namespace.

Block configuration

Type: Object [ { key: value } ]