How to Register a WordPress Block with block.json

Modern WordPress blocks are defined by a single metadata file: block.json. It tells WordPress the block’s name, what it supports, and where its scripts and styles live. Registering a block is then a one-liner. Here is how it fits together.

Why block.json

Before block.json, registering a block meant repeating the same details in both JavaScript and PHP. Now you declare everything once in block.json, and both sides read from it. It is the officially recommended approach and what @wordpress/create-block scaffolds.

Generate it

Open the block.json Generator.
Set the name (namespace/block, like my-plugin/hero), title, category, icon, and description.
Toggle the supports you need, then copy the block.json and the matching register snippet.

The supports that matter

The supports object turns on editor features without you writing the UI:

align: lets users set wide and full width.
color: adds background and text color controls.
spacing: adds padding and margin controls.
typography: adds font size and related controls.
html: whether users can edit the block’s raw HTML (often false for custom blocks).

Enabling these gives editors familiar controls for free.

Register it in PHP

With block.json in place, registration is one line on the init hook:

function tc_register_blocks() {
    register_block_type( __DIR__ . '/build/hero' );
}
add_action( 'init', 'tc_register_blocks' );

Point it at the built folder (where your tooling outputs the compiled files and block.json). The generator gives you this snippet too.

Static vs dynamic

If your block renders fixed markup, it is static. If it should render on the server (for example, to show the latest posts), it is dynamic: add a render file in block.json and output the markup in PHP. The generator includes the render line when you mark the block dynamic.

Building a plugin around it? Check your plugin readme before release.
Need a hook to extend behavior? Use the WordPress Hook Finder.
Reusable PHP snippets? See the WordPress Snippet Generator.

Define the block once in block.json, enable the supports you want, and register it with a single line. That is the modern block workflow.