WordpressHow-ToBeginner · 4 min read

How to Create Custom Block in WordPress Easily

To create a custom block in WordPress, register the block using registerBlockType in JavaScript and enqueue the block script in PHP. This lets you add your own block with custom content and controls inside the WordPress editor.

📐

Syntax

Creating a custom block involves two main parts: registering the block in JavaScript and enqueuing the script in PHP.

registerBlockType(): Registers the block with a unique name and settings.
edit(): Defines the block's editor interface.
save(): Defines how the block content is saved and rendered.
enqueue_block_editor_assets(): PHP hook to load the block's JavaScript in the editor.

javascript

registerBlockType('namespace/block-name', {
  title: 'Block Title',
  icon: 'smiley',
  category: 'common',
  edit: () => {
    return <p>Hello from custom block!</p>;
  },
  save: () => {
    return <p>Hello from custom block!</p>;
  },
});

💻

Example

This example shows a simple custom block that displays a greeting message in the editor and on the site.

The PHP code enqueues the block script, and the JavaScript registers the block with edit and save functions.

php and javascript

<?php
// In your plugin or theme's functions.php
function my_custom_block_assets() {
  wp_enqueue_script(
    'my-custom-block',
    plugins_url('block.js', __FILE__),
    array('wp-blocks', 'wp-element', 'wp-editor'),
    filemtime(plugin_dir_path(__FILE__) . 'block.js')
  );
}
add_action('enqueue_block_editor_assets', 'my_custom_block_assets');

// block.js
import { registerBlockType } from '@wordpress/blocks';
import { createElement } from '@wordpress/element';

registerBlockType('myplugin/greeting-block', {
  title: 'Greeting Block',
  icon: 'smiley',
  category: 'widgets',
  edit: () => createElement('p', null, 'Hello from the editor!'),
  save: () => createElement('p', null, 'Hello from the site!'),
});

Output

In the WordPress editor, a block named 'Greeting Block' appears showing 'Hello from the editor!'. On the published site, it shows 'Hello from the site!'.

⚠️

Common Pitfalls

Forgetting to enqueue the block script with enqueue_block_editor_assets causes the block not to appear.
Using the same block name as a core or other plugin block causes conflicts; always use a unique namespace.
Not returning valid JSX or elements in edit and save leads to errors.
Not including required dependencies like wp-blocks, wp-element, and wp-editor in the script enqueue.

php

/* Wrong: Missing enqueue hook */
function wrong_enqueue() {
  wp_enqueue_script('my-block', 'block.js');
}
// Block won't load in editor

/* Right: Correct enqueue with hook */
add_action('enqueue_block_editor_assets', 'my_custom_block_assets');

📊

Quick Reference

Step	Description
1. Create block.js	Write JavaScript to register your block with edit and save functions.
2. Enqueue script	Use PHP hook enqueue_block_editor_assets to load block.js in editor.
3. Use unique name	Name your block as 'namespace/block-name' to avoid conflicts.
4. Test block	Check block appears in editor and renders correctly on site.

✅

Key Takeaways

Enqueue your block script in PHP using enqueue_block_editor_assets hook.

Define clear edit and save functions to control block editor and front-end output.

Always include required WordPress script dependencies when enqueuing.

Test your block in the editor and on the live site to ensure it works correctly.