Getting Started with WordPress Block Development: A Beginner’s Guide

WordPress Block Development is an essential skill for modern WordPress developers, enabling them to create custom blocks for the Gutenberg editor. This guide will walk you through everything you need to know to get started, from setting up your environment to building and registering your first custom block.

Understanding WordPress Block Development

What is a WordPress Block?

A WordPress block is a modular content unit used in the Block Editor (Gutenberg). Everything in the editor—from paragraphs to images and buttons—is a block. Custom block development allows developers to extend WordPress and create tailored experiences for users.

Why Build Custom Blocks?

• Extend WordPress functionality beyond default blocks.
• Improve content management with reusable custom components.
• Enhance site performance by avoiding extra plugins.
• Gain better control over block styling and behavior.

Setting Up Your Development Environment

Prerequisites

Before you begin, ensure you have the following installed on your computer:

• Node.js & npm (to manage dependencies) → Download Here
• WordPress Development Environment (LocalWP, XAMPP, Docker, or a local WordPress installation)
• Code Editor (VS Code recommended)
• WordPress Plugin Folder (where you’ll place your custom block)

Installing the WordPress Block Development Toolkit

WordPress provides a command-line tool to scaffold new block projects:

npx @wordpress/create-block my-custom-block

This command will:

• Create a new block project in the my-custom-block directory.
• Set up the necessary files and dependencies automatically.

After installation, navigate into the directory:

cd my-custom-block
npm start

This starts a development server that automatically updates changes in your block.

Understanding the Block Structure

A typical block directory contains:

• build/ → Contains compiled JavaScript and styles for production.
• src/ → Contains the block’s main source code.
• src/block.json → Defines block metadata.
• src/index.js → The entry point for registering the block.

Creating a Simple Custom Block

Let’s modify the generated block to create a simple “Hello World” block.

Step 1: Update block.json

This file defines the block’s settings, such as title, category, and attributes.

{
  "apiVersion": 3,
  "name": "create-block/my-custom-block",
  "title": "My Custom Block",
  "category": "widgets",
  "icon": "smiley",
  "editorScript": "file:./index.js"
}

Step 2: Modify src/edit.js

The edit.js file controls how the block appears in the editor.

import { useBlockProps } from '@wordpress/block-editor';

export default () => {
    return <p {...useBlockProps()}>Hello, World! This is my custom block.</p>;
};

Step 3: Modify src/save.js

The save.js file controls how the block appears on the frontend.

export default () => {
	return (
		<p { ...useBlockProps.save() }>
			{ 'Hello, World! This is my custom block.' }
		</p>
	);
}

Step 4: Build the Block

Run the following command to compile your block’s JavaScript and assets:

npm run build

Step 5: Activate the Plugin

• Go to your WordPress dashboard.
• Navigate to Plugins > Installed Plugins.
• Activate your custom block plugin.

Now, you can add the “Hello World” block inside the WordPress editor.

5. Enhancing Your Block

Adding Block Attributes

Block attributes store dynamic data that users can modify. Example:

"attributes": {
  "content": {
    "type": "string",
    "default": "Hello, World!"
  }
}

Using Controls for User Input

Modify edit.js to include a text input for users to change the block’s text.

import { useBlockProps, RichText } from '@wordpress/block-editor';

const Edit = ({ attributes, setAttributes }) => {
    return (
        <RichText
            {...useBlockProps()}
            tagName="p"
            value={attributes.content}
            onChange={(content) => setAttributes({ content })}
            placeholder="Enter text..."
        />
    );
};

export default Edit;

Modify save.js to display the user input.

import { useBlockProps, RichText } from '@wordpress/block-editor';

const Save = ({ attributes }) => {
    return <RichText.Content {...useBlockProps()} tagName="p" value={attributes.content} />;
};

export default Save;

6. Styling Your Block

Modify src/editor.scss to add editor styles:

.wp-block-create-block-my-custom-block {
	background-color: #da2c2c;
	padding: 10px;
	border-radius: 5px;
}

Modify src/style.scss for frontend styles:

.wp-block-create-block-my-custom-block {
	background-color: #2c3dda;
	padding: 10px;
	border-radius: 5px;
	color: #fff;
}

7. Registering the Block with PHP

WordPress requires a PHP file to register the block when the plugin is activated. Modify my-custom-block.php:

<?php
/**
 * Plugin Name:       My Custom Block
 * Description:       Example block scaffolded with Create Block tool.
 * Version:           0.1.0
 * Author:            Rakesh Lawaju
 *
 * @package CreateBlock
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit; // Exit if accessed directly.
}


function create_block_my_custom_block_block_init() {
	register_block_type( __DIR__ . '/build/my-custom-block' );
}
add_action( 'init', 'create_block_my_custom_block_block_init' );

8. Testing and Deploying the Block

Testing Your Block

• Test in different browsers and WordPress themes.
• Check for console errors using browser developer tools.
• Test with other plugins to ensure compatibility.

Deploying Your Block

• Upload the plugin folder to a live WordPress site.
• Submit your block to the WordPress Plugin Directory if you want to share it with the community.

Conclusion

Congratulations! You have successfully created your first custom WordPress block. From here, you can explore more advanced topics like:

• Dynamic Blocks (blocks that pull data from the database)
• Interactivity with JavaScript (buttons, modals, etc.)
• Block Variations and Patterns