How to Create a Custom Block in Gutenberg Editor (Step-by-Step Guide)

The Gutenberg editor, also known as the Block Editor, allows WordPress users to build rich content layouts using blocks. In this tutorial, you will learn how to create your own custom Gutenberg block from scratch.

What is a Gutenberg Block?

A Gutenberg block is a modular content element used in WordPress posts and pages. Examples include paragraphs, images, headings, buttons, etc. By creating a custom block, you can add new design or functionality tailored to your website’s needs.

---

Prerequisites

To create a custom block, you should have:

• Basic knowledge of WordPress, HTML, CSS, and JavaScript (React/JSX).
• Access to your theme or a custom plugin to add the block code.

---

Step 1: Setup Your Development Environment

1. Install Node.js (https://nodejs.org/)
2. Install WordPress locally using LocalWP, MAMP, XAMPP, or any preferred method.

---

Step 2: Create a Plugin for Your Block

1. Go to your WordPress site’s wp-content/plugins directory.
2. Create a folder, for example:
   my-custom-block
3. Inside the folder, create a file:
   my-custom-block.php

Add the following code to my-custom-block.php:

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

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

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

add_action('init', 'my_custom_block_register');
?>

---

Step 3: Create the Block JavaScript (block.js)

In the same plugin folder, create block.js and add:

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

registerBlockType('myplugin/my-custom-block', {
    title: 'My Custom Block',
    icon: 'smiley',
    category: 'common',
    attributes: {
        content: { type: 'string' }
    },
    edit: ({ attributes, setAttributes }) => {
        const onChangeContent = (newContent) => {
            setAttributes({ content: newContent });
        };

        return (
            <RichText
                tagName="p"
                value={attributes.content}
                onChange={onChangeContent}
                placeholder="Write something here..."
            />
        );
    },
    save: ({ attributes }) => {
        return <RichText.Content tagName="p" value={attributes.content} />;
    },
});

---

Step 4: Activate the Plugin

1. Go to WordPress Admin → Plugins.
2. Activate My Custom Block.

---

Step 5: Use the Block in the Editor

1. Go to Posts → Add New.
2. Click the + icon and search for My Custom Block.
3. Add it to the page, type something, and publish!

---

Step 6: Style Your Block (Optional)

You can create a style.css and editor.css in your plugin folder and enqueue them for styling your block on the front-end and editor.

Example PHP addition:

wp_register_style(
    'my-custom-block-style',
    plugins_url('style.css', __FILE__),
    array(),
    filemtime(plugin_dir_path(__FILE__) . 'style.css')
);

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

---

Conclusion

Creating custom Gutenberg blocks opens up endless possibilities for customizing your WordPress site’s content editing experience. With the steps above, you’ve built a simple block — from here, you can add more complex features, controls, and styling.

👉 Bonus Tip: Use the official @wordpress/create-block package for faster block scaffolding if you’re comfortable with command-line tools.

---