Skip to content

How to Create Custom WordPress Block

This guide walks you through creating custom WordPress blocks from scratch using the Gutenberg editor. You’ll learn to code blocks with JavaScript and PHP, register them properly, and make them reusable across your site.

Key Takeaways

  • Understand the Block Editor: Learn how Gutenberg works and why custom blocks enhance content flexibility.
  • Set up your development environment: Use tools like Node.js, npm, and a local WordPress install to build safely.
  • Create a plugin for your block: Keep your custom block separate from themes for better portability and updates.
  • Write block code with JavaScript and React: Use @wordpress/scripts and JSX to define block behavior and UI.
  • Register the block in PHP: Connect your JavaScript block to WordPress so it appears in the editor.
  • Test and debug your block: Use browser tools and WordPress logs to fix issues quickly.
  • Reuse and share your block: Package it as a plugin for use on other sites or share with the community.

Introduction

WordPress has evolved far beyond simple blog posts. With the introduction of the Gutenberg block editor, users can now build rich, dynamic layouts using reusable content blocks. But what if the default blocks don’t meet your needs? That’s where custom WordPress blocks come in.

In this guide, you’ll learn how to create a custom WordPress block from scratch. Whether you’re a developer looking to extend functionality or a site builder wanting more control over design, this step-by-step tutorial will show you how to build, register, and use your own block. We’ll cover everything from setting up your environment to deploying your block as a plugin.

What Is a Custom WordPress Block?

A custom WordPress block is a reusable piece of content or functionality that you can add to posts and pages using the Gutenberg editor. Unlike standard blocks (like paragraphs or images), custom blocks are built specifically for your site’s needs—think pricing tables, testimonial sliders, or interactive forms.

How to Create Custom WordPress Block

Visual guide about How to Create Custom WordPress Block

Image source: cdn.deliciousbrains.com

Custom blocks are built using JavaScript (typically React), styled with CSS, and registered in WordPress using PHP. They give you full control over how content is displayed and edited, making your site more dynamic and user-friendly.

Prerequisites

Before we begin, make sure you have the following:

  • A local or live WordPress installation (version 5.0 or higher)
  • Node.js and npm installed on your computer
  • Basic knowledge of JavaScript, PHP, and HTML
  • A code editor like VS Code

If you’re new to WordPress development, consider reviewing our guide on is WordPress easy to install to get your environment ready.

Step 1: Set Up Your Development Environment

To create a custom block, you’ll need a safe place to test your code. A local WordPress install using tools like Local by Flywheel or XAMPP is ideal. This lets you experiment without affecting a live site.

Install Node.js and npm

Custom blocks use modern JavaScript tools. Download and install Node.js from nodejs.org. This includes npm (Node Package Manager), which we’ll use to install dependencies.

Create a Plugin Folder

Navigate to your WordPress installation’s wp-content/plugins directory. Create a new folder called custom-test-block. This will hold all your block files.

Step 2: Initialize Your Plugin

Every WordPress plugin needs a main PHP file. Inside your custom-test-block folder, create a file named custom-test-block.php and add the following code:

This tells WordPress that your folder is a plugin. You can now activate it from the WordPress admin dashboard under Plugins.
Step 3: Set Up Block Development Tools
WordPress provides a handy package called @wordpress/scripts to simplify block development. It handles bundling, transpiling, and more.
Initialize npm in Your Plugin Folder
Open your terminal, navigate to your plugin folder, and run:
npm init -y

This creates a package.json file. Next, install the required packages:
npm install @wordpress/scripts --save-dev

Update package.json Scripts
Edit your package.json file and add these scripts under the "scripts" section:
"scripts": {
  "build": "wp-scripts build",
  "start": "wp-scripts start"
}

Now you can use npm run start to develop in real-time or npm run build to compile for production.
Step 4: Create the Block Source Files
Inside your plugin folder, create a new directory called src. This will hold your JavaScript files.
Create the Main Block File
In the src folder, create a file named index.js. This is where you’ll define your block.
Add the following code to register a simple "Hello World" block:
import { registerBlockType } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';

registerBlockType('custom/test-block', {
  title: __('Test Block', 'custom'),
  icon: 'smiley',
  category: 'widgets',
  edit: () => {
    return 
Hello from the editor!
;
  },
  save: () => {
    return 
Hello from the frontend!
;
  },
});

This block has two parts: edit (what users see in the editor) and save (what gets saved to the database).
Add a Block.json File (Optional but Recommended)
WordPress supports a block.json file for metadata. Create this file in your src folder:
{
  "name": "custom/test-block",
  "title": "Test Block",
  "icon": "smiley",
  "category": "widgets",
  "apiVersion": 2,
  "editorScript": "file:./index.js"
}

This helps WordPress understand your block structure and improves performance.
Step 5: Register the Block in PHP
Now you need to tell WordPress about your block. Go back to your custom-test-block.php and add the following code:
function custom_test_block_init() {
  register_block_type(__DIR__ . '/build');
}
add_action('init', 'custom_test_block_init');

This function registers your block using the compiled files in the build directory (created when you run npm run build).
Step 6: Build and Test Your Block
Run the following command in your terminal:
npm run build

This compiles your JavaScript and outputs it to a build folder. WordPress will load these files when your block is used.
Activate the Plugin
Go to your WordPress admin dashboard, navigate to Plugins, and activate Custom Test Block.
Use Your Block
Create a new post or page. Click the + button to add a block. Search for "Test Block". You should see your custom block in the list. Add it and see your "Hello" message appear.
Enhancing Your Block
Now that your block works, you can add features like attributes, styles, and dynamic content.
Add Attributes
Attributes let users customize the block. For example, let’s add a text field:
attributes: {
  message: {
    type: 'string',
    default: 'Hello World',
  },
},

Update the edit and save functions to use this attribute:
edit: (props) => {
  const { attributes, setAttributes } = props;
  return (
     setAttributes({ message: e.target.value })}
    />
  );
},
save: (props) => {
  return 
{props.attributes.message}
;
},

Add CSS Styling
Create a style.css file in your src folder and import it in index.js:
import './style.css';

Then add styles like:
.custom-test-block {
  background: #f0f0f0;
  padding: 20px;
  border-radius: 8px;
}

Troubleshooting Common Issues
  • Block not appearing? Make sure you’ve run npm run build and activated the plugin.
  • JavaScript errors? Check the browser console for clues. Common issues include missing dependencies or syntax errors.
  • Changes not showing? Clear your browser cache and rebuild the block.
  • Block not saving? Ensure your save function returns valid React elements.
Conclusion
Creating a custom WordPress block gives you powerful control over your site’s content. By following this guide, you’ve learned how to set up a development environment, write block code with JavaScript and React, register it in PHP, and test it in the editor.
Custom blocks are perfect for adding unique features like pricing tables, team profiles, or interactive forms. Once you’re comfortable, you can explore advanced topics like dynamic blocks, server-side rendering, and block variations.
For more WordPress development tips, check out our guide on the best WordPress theme for SEO and speed or learn how to create a WordPress theme with Elementor.