How to Develop a Custom Gutenberg Block for WordPress

Introduction

The Gutenberg editor has revolutionized the WordPress content creation experience by introducing block-based editing. As a WordPress developer, you can harness the power of custom Gutenberg blocks to provide tailored content solutions for your clients or projects. In this guide, we’ll walk you through the process of developing a custom Gutenberg block from scratch.

Step 1: Set Up Your Development Environment

Before you begin, ensure that your local environment is ready for block development:

• WordPress installation: Set up a local WordPress instance.
• Node.js and npm: Ensure you have Node.js and npm installed to manage JavaScript packages.
• Create a plugin: If you’re building a block for a specific plugin, start by creating a new plugin. Otherwise, you can add the block code to your theme’s functions.php or a custom block file.

Create your plugin folder in wp-content/plugins/, for example, my-custom-block, and create two files inside it:

my-custom-block/
  my-custom-block.php
  block.js

Step 2: Register the Block

In your plugin file my-custom-block.php, you’ll register the block in WordPress. Use the following code to create a basic structure:

<?php
/*
Plugin Name: My Custom Block
Description: A simple custom Gutenberg block
Version: 1.0
Author: Your Name
*/

function register_my_custom_block() {
    wp_register_script(
        'my-custom-block-script',
        plugins_url( 'block.js', __FILE__ ),
        array( 'wp-blocks', 'wp-editor', 'wp-element' )
    );

    register_block_type( 'myplugin/my-custom-block', array(
        'editor_script' => 'my-custom-block-script',
    ));
}

add_action( 'init', 'register_my_custom_block' );

Step 3: Write the Block Script

In block.js, you’ll write the block’s JavaScript using React (JSX). This will define how the block looks and behaves in the editor.

const { registerBlockType } = wp.blocks;
const { RichText } = wp.blockEditor;

registerBlockType('myplugin/my-custom-block', {
    title: 'Custom Block',
    icon: 'smiley',
    category: 'common',
    attributes: {
        content: {
            type: 'string',
            source: 'html',
            selector: 'p',
        },
    },
    edit({ attributes, setAttributes }) {
        return (
            <RichText
                tagName="p"
                value={attributes.content}
                onChange={(content) => setAttributes({ content })}
                placeholder="Write something..."
            />
        );
    },
    save({ attributes }) {
        return <RichText.Content tagName="p" value={attributes.content} />;
    },
});

Step 4: Enqueue the Block’s Assets

Make sure WordPress enqueues your block’s assets by registering the block type and associating it with the script from block.js. The editor script handles how the block behaves within the Gutenberg editor, and the saved content structure ensures correct display on the frontend.

Step 5: Test and Customize

Now that the block is registered, activate the plugin, go to the Gutenberg editor, and search for your custom block by name. Test it by adding content. You can extend the block by adding styles, additional functionality, or other block settings.

Conclusion

Developing custom Gutenberg blocks gives you full control over the editing experience in WordPress. Whether for personal projects or client work, the flexibility provided by custom blocks allows for a highly personalized, dynamic content creation workflow.