Developer · Guide
How to Create a Custom Block in WordPress

Short answer
To create a custom block in WordPress, scaffold a block plugin with the create-block tool, describe the block in block.json, write its edit and save parts in JavaScript, register it on the server with register_block_type on the init hook, then build the plugin and activate it. The block then appears in the editor inserter.
Key takeaways
- Custom blocks live in a plugin and are registered on both the server and the client using block.json.
- The create-block tool scaffolds the plugin and build setup, and it needs Node 22.13.0 or later.
- Block API version 3 is current, and it arrived with WordPress 6.3.
- Server registration is required for dynamic rendering, block supports, and theme.json styles.
- A static block saves HTML in the post, while a dynamic block builds HTML fresh on each view.
What is a custom block in WordPress?
A custom block is a small plugin that adds a new block type to the editor, with its own settings, markup, and styles.
A block is the unit the editor uses for each piece of content, such as a paragraph, an image, or a heading. A custom block gives your site a content piece the core blocks do not offer, such as a notice box or a staff card.
Developer.WordPress.org states that blocks in WordPress are typically bundled in a plugin and registered on both the server and the client side using block.json metadata (checked November 2026).
Server registration matters because some features only work when WordPress knows about the block on the server. Developer.WordPress.org states that dynamic rendering, block supports, block hooks, and style variations need server-side registration (checked November 2026).
A guide on how to use block patterns in WordPress covers ready-made groups of blocks when you need a layout, not a new block type.
What do you need before you start?
You need a local WordPress site, a code editor, and Node.js with npm installed on your computer.
Developer.WordPress.org states that the create-block package is an officially supported tool to scaffold the files needed to create and register a block (checked November 2026).
The same page states that create-block installs wp-scripts and adds the most common scripts to the package.json file, so you do not set up webpack, Babel, or ESLint by hand (checked November 2026).
The create-block package page states that it requires Node version 22.13.0 or later, so check your Node version before you run it (checked November 2026). Learn WordPress offers a tutorial on the create-block tool if you want a guided walk through the same steps.
You also need basic JavaScript and PHP. JavaScript builds the editor view, and PHP registers the block on the server. A guide on block themes vs classic themes explains where blocks fit in each theme type.
How do you scaffold a block with create-block?
Run one npx command in your plugins folder to scaffold a working block plugin with a build setup.
Open a terminal, move into the plugins folder of your local WordPress install, and run the command below, using your own slug in place of todo-list.
npx @wordpress/create-block@latest todo-list
cd todo-list
Developer.WordPress.org states that the slug you pass defines the folder name for the scaffolded plugin and the internal block name (checked November 2026).
The scaffold installs wp-scripts and adds scripts to package.json. Developer.WordPress.org states that the two scripts you will use most are start and build, since they handle the build step (checked November 2026).
Run npm run start while you work, since it rebuilds the block each time you save a change. Run npm run build when you are ready to ship, since it makes production-ready files.
If you run the command with no slug, create-block asks for the settings step by step in interactive mode. Developer.WordPress.org states that you can also pass options on the command line, such as a namespace and a dynamic variant, to skip the prompts (checked November 2026).
What goes in block.json?
The block.json file holds the block metadata, such as its name, title, category, attributes, and asset files.
Developer.WordPress.org states that starting with WordPress 5.8, block.json is the recommended way to register block types with both PHP and JavaScript (checked November 2026).
The name is required and must use the form namespace/block-name, where the namespace is your plugin or theme name. Developer.WordPress.org states that a block name can only contain lowercase letters, numbers, and dashes, with at most one forward slash, and it must begin with a letter (checked November 2026).
The current Block API version is 3, which Developer.WordPress.org states was introduced in WordPress 6.3 (checked November 2026). Set apiVersion to 3 in a new block.
| Field | What it does | Example value |
|---|---|---|
| name | Unique id for the block | my-plugin/notice |
| title | Label shown in the inserter | Notice |
| category | Inserter group for the block | text |
| apiVersion | Block API version to use | 3 |
| attributes | Data the block stores | message as a string |
| editorScript | JavaScript for the editor | file:./index.js |
| style | CSS for editor and front end | file:./style.css |
| render | PHP file for dynamic output | file:./render.php |
The category must be one of the six core groups, unless you register your own. Developer.WordPress.org lists the core categories as text, media, design, widgets, theme, and embed (checked November 2026).
Add the schema line "$schema": "https://schemas.wp.org/trunk/block.json" at the top of the file. Schemas.wp.org hosts the schema that editors use for tooltips, autocomplete, and validation.
How do you write the edit and save parts?
The edit part is the React view shown in the editor, and the save part returns the markup stored in the post.
In the scaffolded src/index.js file, import registerBlockType from the @wordpress/blocks package and the metadata from block.json. Call registerBlockType with the block name from the metadata and an object with edit and save.
The edit function returns what the author sees and changes in the editor. Use the useBlockProps hook from the @wordpress/block-editor package in edit, and useBlockProps.save in save, so WordPress adds the right wrapper attributes.
Attributes hold the block data, such as a message string or a color choice. Declare each attribute in block.json with a type, such as string or number, so the editor knows how to store it.
Keep the save output simple and stable. If you change the saved markup later, old posts with the block can fail validation and show an error in the editor.
A guide on how to use block bindings in WordPress shows how a block can pull its content from post data instead of storing it by hand.
How do you register the block on the server?
Register the block in the main plugin PHP file on the init hook, pointing at the build folder that holds block.json.
Since WordPress 6.8, the recommended call is wp_register_block_types_from_metadata_collection, which registers every block in a blocks-manifest.php file in one call. Developer.WordPress.org states that this function requires WordPress 6.8 or later and that the manifest is built by the wp-scripts build-blocks-manifest command (checked November 2026).
For a single block, or when you support older WordPress versions, register_block_type still works. Developer.WordPress.org states that register_block_type reads the metadata from a block.json file and remains valid for plugins with a single block (checked November 2026).
function my_plugin_register_blocks() {
register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'my_plugin_register_blocks' );
Point the path at the build folder, not the src folder. Developer.WordPress.org states that block.json is typically moved from src to build during the build step, so the registration path must point at the build copy (checked November 2026).
A guide on how to use theme.json explains how a server-registered block picks up styles from theme.json.
Should your block be static or dynamic?
Pick a static block when the output never changes, and a dynamic block when the output is built fresh on each page view.
A static block saves its full HTML into the post when the author clicks Save. The front end then shows that saved HTML with no PHP run at view time.
A dynamic block saves only its attributes, and a PHP render callback builds the HTML on each request. Use this for content that changes, such as a date, a post count, or data from another source.
Developer.WordPress.org states that blocks that only need server-side rendering can be registered in PHP alone with the autoRegister flag and a render callback, with no JavaScript registration (checked November 2026).
Make WordPress Core states that PHP-only blocks are meant for blocks that only need server-side rendering and are not meant to be highly interactive (checked November 2026).
The create-block tool can scaffold a dynamic block for you. Pass the variant option on the command line, as in npx @wordpress/create-block@latest my-block --variant=dynamic, and the scaffold wires the render file for you.
Choose static for fixed text and simple layouts. Choose dynamic when the output must stay current without re-saving each post.
How do you check the block works?
Activate the plugin, add the block to a post, save, and view the post on the front end.
Go to Plugins in the dashboard and activate your new plugin. Open a post, click the inserter, search for your block title, and add it to the post.
Fill in the block settings, save the post, and open it in a private browser window. Check that the front end shows the block as you expect, and that the editor shows no validation error when you reopen the post.
If the block does not appear in the inserter, check three things: the plugin is active, the build ran without errors, and the block name in block.json matches the name in the JavaScript registration.
Developer.WordPress.org states that the front-end CSS and JavaScript listed in block.json are only loaded when the block is present on the page, so a missing style on one page may simply mean the block is not on that page (checked November 2026).
A guide on how to create reusable blocks and synced patterns covers the no-code way to reuse a block group across posts.
What mistakes should you avoid?
Avoid a generic namespace, a missing build step, and a save function that changes shape after posts go live.
Do not use create-block, block, or editorial as your namespace, since those names are too generic and can clash with other plugins. Developer.WordPress.org warns against generic names such as create-block and block for this reason (checked November 2026).
Do not edit files in the build folder by hand, since the next build overwrites them. Change the source files in src and rebuild.
Do not skip server registration to save time. Developer.WordPress.org states that the Block Directory can only list blocks from plugins that include a block.json file, so client-only blocks miss that listing (checked November 2026).
Do not change the saved markup of a static block without a plan for old posts. Add a deprecation entry in the JavaScript registration so old content still loads, or switch the block to dynamic rendering.
Frequently asked questions
Can I create a custom block with plain PHP and no build step?
No. A block needs a build step for its JavaScript, since the editor code uses modern JavaScript and JSX that browsers cannot run as written. The create-block tool sets up that build step for you with wp-scripts, and you run npm run start while you work and npm run build to ship.
When should I choose a dynamic block over a static block?
Use a static block for fixed content, such as a styled notice or a callout box, where the saved HTML never needs to change. Use a dynamic block when the output must be built fresh on each view, such as a current date, a post list, or data pulled from another source.
Why does my custom block not appear in the editor inserter?
Check that the plugin is active, that the build ran without errors, and that the block name matches in block.json and in the JavaScript registration. Also confirm the block category is valid and that no other plugin registered the same block name first.
Can I share my custom block with other WordPress sites?
Yes, if the block is registered on the server with block.json. Server registration is what lets WordPress list the block in the block type REST endpoint and in the Block Directory. Client-only blocks miss those listings and several server features.
Does a custom block survive a theme change?
Yes. A custom block lives inside a plugin, so it keeps working when you switch themes. Blocks built into a theme stop working when that theme is deactivated, which is why the handbook recommends bundling blocks in a plugin.
Sources
- Registration of a block WordPress Developer Resources
- Metadata in block.json WordPress Developer Resources
- Get started with create-block WordPress Developer Resources
- Registration - Block API reference WordPress Developer Resources
- Using the create-block tool Learn WordPress
- PHP-only block registration Make WordPress Core
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.


