How to Add Custom Blocks to the Gutenberg Editor in WordPress

While many site administrators find the Gutenberg editor unfamiliar, I personally find it more practical than the classic editor. This tutorial focuses on adding custom blocks directly within your theme, rather than via a plugin.

Loading a Custom Gutenberg Block

First, register and enqueue the block's JavaScript in your theme's functions.php file.

// Load custom Gutenberg block
function my_gutenberg_block() {
    // Register the block script
    wp_register_script(
        'block-js',
        get_template_directory_uri() . '/src/blocks.js',
        array('wp-blocks', 'wp-element', 'wp-editor', 'wp-i18n'),
        '1.0.0'
    );
    // Register the block type
    register_block_type( 'mytheme/custom-block', array(
        'editor_script' => 'block-js'
    ) );
}
add_action( 'init', 'my_gutenberg_block' );

Create blocks.js

Create a src folder in your theme directory and add a blocks.js file. Ensure the path matches the one in wp_register_script.

Edit blocks.js

This file defines the block's functionality.

(function (blocks, element, editor, i18n) {
    var el = element.createElement;
    var RichText = editor.RichText;

    blocks.registerBlockType('mytheme/custom-block', {
        title: 'Test Block',
        icon: 'universal-access-alt',
        category: 'layout',
        attributes: {
            content: {
                type: 'array',
                source: 'children',
                selector: 'p',
            },
        },
        edit: function (props) {
            var content = props.attributes.content;
            function onChangeContent(newContent) {
                props.setAttributes({ content: newContent });
            }
            return el(
                RichText,
                {
                    tagName: 'p',
                    className: props.className,
                    onChange: onChangeContent,
                    value: content,
                }
            );
        },
        save: function (props) {
            return el(RichText.Content, {
                tagName: 'p',
                value: props.attributes.content,
            });
        },
    });
}(
    window.wp.blocks,
    window.wp.element,
    window.wp.editor,
    window.wp.i18n
));

Code Explanation

• registerBlockType: Registers a new block with a unique identifier (namespace/name).
• edit function: Defines the block's interface and behavior in the editor.
• save function: Defines how the block content is saved and rendered on the front end.
• The dependencies (blocks, element, editor, i18n) must match those in the wp_register_script array.

View the Result

After completing these steps, clear your browser cache and refresh the WordPress post editor. Click the "Add Block" (+) button. Your new "Test Block" should appear in the "Layout Elements" category or the category you specified.

This example is a basic demo. For more complex blocks with multiple fields or dynamic content, refer to the official Block Editor Handbook.