How to Create Custom Gutenberg Blocks in WordPress

Quick Summary

Are you looking to transform your WordPress content creation process into something smoother and more efficient? The Gutenberg Editor is here to help. Whether you’re managing a personal blog or developing complex websites, this guide will show you how Gutenberg can enhance your workflow, make designing content easier, and give you the tools to create stunning pages with ease.

What is the Gutenberg Block?

The editor you see here is Gutenberg Editor and blocks on the left-hand side are used in the page/post to create the same. These are the ready-made blocks that come with WordPress installation but you can create your own blocks too. Gutenberg editor was introduced in WordPress 5.0 back in 2018.

Gutenberg makes building pages and posts in WordPress easier and more visual. Instead of writing code or using shortcodes, you can use different “blocks”—like text, images, videos, buttons, and more—to design your content just by dragging and dropping. This gives you more flexibility to create unique layouts, and it’s all built right into WordPress, so you don’t need extra plugins to get started. It’s perfect for both beginners and experienced users who want a smoother way to create beautiful, responsive websites.

Prerequisites to Create Gutenberg Block

• Basic knowledge of React Js
• Node.js version 12.0.0+
• npm version 6.9.0+

How to create a Gutenberg Block?

Suppose you are new to Gutenberg development then you know there are not many tutorials available now. Even if you find some courses then it will have different ways for creating Gutenberg blocks like via WordPress Themes or WordPress Plugins and you might get confused about which way is better to use.

A common question for beginners is: “Are WordPress plugins safe?” Generally, WordPress plugins are safe if sourced properly. However, for businesses looking for tailored functionality and maximum security, exploring custom solutions might be a better option.

Learn more in 5 Reasons Why a Custom WordPress Plugin Is Better for Your Business.

So here is the simple and latest way to create such a Gutenberg block.

1. Go to the plugins directory in your WordPress setup
2. Open your terminal there.
3. Write command npx @wordpress/create-block demo-gutenberg-block
4. Wait for some minutes and your own Gutenberg Block will be created automatically.

Once your local environment is up and running, you can set up a starter block by simply running the npx @wordpress/create-block command, and it will provide all the files and folders you need to create the plugin skeleton and register a new block.

Read more: Top 5 Best WordPress Plugins for eCommerce Business Websites

From your Command Line tool, navigate to the /wp-content/plugins/ directory and run the following command:

When asked to confirm, enter y to proceed:

The process takes a few moments. When it’s complete, you should get the following response:

And that’s it!

Once your Gutenberg block is set up, consider exploring innovative use cases, such as integrating AI functionalities into your WordPress plugins. For inspiration, check out Top 5 WordPress Plugin Development Ideas Using ChatGPT and OpenAI in 2024

Error Handling

You might run into an error like below

You can fix this by following commands:

Directory Introduction

After successful completion, you will see the folder structure shown below in your Gutenberg Block plugin, the src folder is where all the code will be written.

As shown in the above image, the src folder contains 3 Javascript files and 2 SCSS files respectively.

edit.js: This file contains the JavaScript code that defines the behavior and appearance of the block in the WordPress block editor (the backend). It includes the logic for how the block behaves when being edited.

1. editor.scss: This file is used for styling the block when it’s being edited within the Gutenberg editor. It ensures that the block’s appearance in the editor matches its intended look.
2. index.js: This file is crucial for registering and defining the block’s attributes and settings in Gutenberg. It’s where you set up the block’s schema and configuration.
3. save.js: This file contains the JavaScript code that defines how the block should be rendered on the frontend of the site. It determines the block’s final output that users will see on the live site.
4. style.scss: This file is used for styling the block on the frontend of the site, ensuring that it looks as intended when viewed by site visitors.

The Plugin File (my-first-block.php)

The register_block_type function registers a block type on the server using the metadata stored in the block.json file.

The function takes two parameters:

• The block type name including namespace, or a path to the folder where the block.json file is located, or a complete WP_Block_Type object
• An array of block type arguments

In the code above, the __DIR__ magic constant returns the current folder. That means that the block.json file resides in the /build subfolder.

The package.json File

The package.json file defines JavaScript properties and scripts for your project. This is where you can install your project dependencies.

The scripts property is a dictionary containing commands that are run at various times in the lifecycle of a package using npm run [cmd].

We’ll be using the following commands:

• npm run build — create a (compressed) production build
• npm run start or npm start — create an (uncompressed) development build

dependencies and devDependencies are two objects mapping a package name to a version. dependencies are required in production, while dev dependencies are only needed for local development.

The block.json File

Starting with WordPress 5.8, the block.json metadata file is the canonical way to register block types.

Having a block.json file provides several benefits, including improved performance and better visibility.

Here’s the full list of default properties:

• apiVersion — the version of the API used by the block (current version is 2)
• name — a unique identifier for a block including a namespace
• version — the current version of a block
• title — a display title for a block
• category — a block category
• icon — a Dashicon slug or a custom SVG icon
• description — a short description visible in the block inspector
• supports — a set of options to control features used in the editor
• textdomain — the plugin text-domain
• editorScript — editor script definition
• editorStyle — editor style definition
• style — provides alternative styles for a block

In addition to the properties listed above, you can (and probably will) define attributes objects providing information about data stored by your block. In your block.json you can set any number of attributes in key/value pairs, where the key is the attribute name and the value is the attribute definition.

Take a look at the following example of attribute definitions:

"attributes": {
"align": {
"type": "string",
"default": "none"
},
"link": {
"type": "string",
"default": "https://example.com"
}
},

The src Folder

The src folder is where the development happens. In that folder, you’ll find the following files:

index.js

The index.js file is your starting point. 

The first statement imports the registerBlockType function from the @wordpress/blocks package. The following import statements import the stylesheet along with the Edit and save functions and a metadata object from the block.json file.

The registerBlockType function registers the component on the client. The function takes two parameters: a block name and a block configuration object.

The Edit function provides the block interface as rendered in the block editor, while the save function provides the structure that will be serialized and saved into the database.

edit.js

edit.js is where you’ll build the block admin interface:

save.js

The save.js file is where we build the block structure to be saved into the database.

editor.scss and style.scss

Apart from the scripts, two SASS files reside in the src folders. The editor.scss file contains the styles applied to the block in the editor’s context, while the style.scss file contains the styles of the block for display in the frontend as well as in the editor.

The node_modules and build Folders

The node_modules folder contains node modules and their dependencies.
The build folder contains the JS and CSS files resulting from the build process.

Now run the following command:

This enables you to run the plugin in development mode.

Conclusion

Creating custom Gutenberg blocks empowers developers to uncover the full potential of WordPress, enabling tailored solutions for unique website needs. By following the steps outlined in this guide, you can enhance your content creation process while ensuring scalability, flexibility, and seamless user experiences.

WordPress

Krunal Bhimajiyani

Software Engineer