How to Build a Custom Gutenberg Block from Scratch: A Step-by-Step Guide

Gutenberg, WordPress’s block editor, has revolutionized the way we create content. But did you know you can create your own custom Gutenberg blocks to extend its functionality? In this guide, we’ll walk you through the process of building a custom Gutenberg block from scratch. Whether you’re a beginner or an experienced developer, this tutorial will help you unlock the full potential of WordPress development.

What is a Gutenberg Block?

Gutenberg blocks are the building blocks of the WordPress block editor. They allow users to add and arrange content elements like paragraphs, images, buttons, and more. By creating custom blocks, you can tailor the editor to meet specific needs, making it easier for clients or users to manage their content.

Why Build a Custom Gutenberg Block?

• Enhanced Flexibility: Create blocks tailored to your website’s unique requirements.
• Improved User Experience: Simplify content creation for non-technical users.
• Reusability: Use your custom blocks across multiple projects.
• Performance Optimization: Avoid bloated plugins by building lightweight, custom solutions.

Prerequisites

Before we dive in, ensure you have the following:

• A local WordPress development environment (e.g., Local by Flywheel, XAMPP).
• Basic knowledge of JavaScript (ES6), React, and PHP.
• Node.js and npm installed on your machine.

Step 1: Set Up Your Development Environment

• Install WordPress: Set up a fresh WordPress installation on your local server.
• Create a Plugin Folder: Navigate to wp-content/plugins and create a new folder for your custom block (e.g., custom-gutenberg-block).
• Initialize npm: Open your terminal, navigate to the plugin folder, and run:

npm init -y

This will create a package.json file for managing dependencies.

Step 2: Register Your Block

• Create the Main Plugin File: Inside your plugin folder, create a php file (e.g., custom-gutenberg-block.php) and add the following code:

<?php
/*
Plugin Name: Custom Gutenberg Block
Description: A custom Gutenberg block created from scratch.
Version: 1.0
Author: Your Name
*/

function custom_gutenberg_block_init() {
    register_block_type(__DIR__ . '/build');
}
add_action('init', 'custom_gutenberg_block_init');
?>

• Create the Block Folder: Inside your plugin folder, create a src folder to store your block’s JavaScript and CSS files.

Step 3: Build Your Block with React

• Install Dependencies: Run the following commands to install the necessary packages:

npm install @wordpress/scripts --save-dev

• Create the Block File: Inside the src folder, create an index.js file and add the following code:

import { registerBlockType } from '@wordpress/blocks';
import { RichText } from '@wordpress/block-editor';

registerBlockType('custom-gutenberg-block/example', {
    title: 'Custom Block',
    icon: 'smiley',
    category: 'common',
    attributes: {
        content: {
            type: 'string',
            source: 'html',
            selector: 'p',
        },
    },
    edit: (props) => {
        const { attributes, setAttributes } = props;
        const { content } = attributes;

        const onChangeContent = (newContent) => {
            setAttributes({ content: newContent });
        };

        return (
            <RichText
                tagName="p"
                onChange={onChangeContent}
                value={content}
            />
        );
    },
    save: (props) => {
        const { attributes } = props;
        const { content } = attributes;

        return <RichText.Content tagName="p" value={content} />;
    },
});

• Build the Block: Run the following command to compile your block:

npx wp-scripts build

Step 4: Test Your Custom Block

• Activate the Plugin: Go to your WordPress admin dashboard, navigate to Plugins, and activate your custom block plugin.
• Add the Block: Create a new post or page, and search for your custom block (e.g., “Custom Block”).
• Customize and Publish: Use the block to add content and see it in action!

Step 5: Add Styles (Optional)

To style your block, create a style.css file in the src folder and import it into your index.js file:

import './style.css';

Then, rebuild your block using npx wp-scripts build.

Conclusion

Building a custom Gutenberg block from scratch may seem daunting at first, but with the right tools and knowledge, it’s a rewarding experience. By following this guide, you’ve learned how to create a simple yet functional block that can be extended to meet your specific needs.

Ready to take your WordPress development skills to the next level? Start experimenting with custom blocks today and unlock the full potential of the Gutenberg editor!

Once your block is working, it is worth zooming out to the theme it lives in — see how to build high-performance block themes in WordPress 6.5+ so your custom blocks render inside a genuinely fast, modern theme, or go the classic route and learn how to build a custom WordPress theme from scratch.