This is a detailed tutorial series covering how to create your own custom WordPress Gutenberg blocks. It’s for you who are a theme or plugin developer and are, like myself, frustrated with the lack of documentation. Most of what I’ve learned when it comes to developing in the new Javascript world of WordPress is through trial and error, vigorously experimenting, and reading everything related I’ve come over. And so I thought I could gather everything I’ve learned so far into a large tutorial.
Through 10 parts this tutorial aims to teach you how to write your own custom blocks. No matter what they are for, starting at the very basics and working up to more complex features. I recommend that you write out everything yourself instead of copy+pasting the code. That’s the best way to learn! Follow the series from step 1 to 10 as we’ll build on top of the block as we advance through.
What you need to know before we start
Before we plunge into the steps; a disclaimer. There’s a few things you should already know beforehand about what this series is and what it isn’t.
The programming languages
You need to know Javascript – that’s a given. No need to be an expert, but this is not a Javascript tutorial. As for ECMAScript Javascript version; you can write in ES5 and not worry about compiling your code with Babel and stuff. However this series is written with ES6 and ESNext code. Don’t worry – step 1 is dedicated to guide you in setting up a development environment ready to code in ESNext with all their new syntaxes.
As you probably know Gutenberg is based on React JS. This series is not a React tutorial either, and assumes basic knowledge of React and how it works. Again there’s no need to be an expert. As React has been around a while there are plenty of good tutorials, documentation, and resources dedicated to teach you React. So I recommend looking up these first.
This series is focused on learning the Javascript, React and JSX parts and not concerned with styling / CSS. As the goal for your block can be drastically different I have chosen to not focus on styling and only provided very basic HTML. It’s up to you to add your styling and the necessary HTML output to make your block render exactly like you need it.
This tutorial’s age
And finally please consider the time this series was written. Gutenberg is still pretty new but is drastically changing and being improved.
If you are finding this in the far future some code might be deprecated or replaced with better methods. This guide was written in and finalized in WordPress version 5.2.3 (end of year 2019).
What you’ll learn
In the first parts we focus on the basics. We set up a development environment with running compilation of our code. And the basics of how to register a block and the necessary PHP parts of it as well. We’ll learn about the huge library of components and methods available to us from WordPress Gutenberg.
Moving on we’ll learn about how to add sections and settings for our block in the editor sidebar (Inspector) as well as customizing the toolbar. Along the way we’ll touch a lot of different input types and how to use Gutenberg’s component for these. And of course we’ll learn how to save, update and output the saved information to our block – and how that works behind the scenes.
At the end we’ll look at more advanced things like dynamic blocks and how to use PHP to render the block output. And finally how to make post queries inside the editor – allowing the user to select a post from a list for render.
Table of Contents
Below you’ll find direct links to each part in the series.
- Part 1: Setting up the Development Environment
In the first part of this tutorial series of how to create custom Gutenberg blocks we need to set up our development environment. We need a place where we can write our code in ES6/ESNext syntaxes and compiling it on the go to.
- Part 2: Registering a Block
In this part we will write Javascript to register and configure our custom block. At the end we’ll register the script with PHP and do the necessary PHP code for WordPress to recognize it as a new block.
- Part 3: Props and WordPress Components
In the previous step we learned how to register a custom block, both in Javascript and in PHP. In this step we’ll learn how to use WordPress’ components for adding different kind of fields and settings.
- Part 4: Attributes
In this part we’ll look at how to define attributes, fetching their values and update them. With attributes we can accept input from the editor, save it and output it however we choose.
- Part 5: Adding Inspector Settings
In this step we’ll focus on what WordPress (at least in code) calls Inspector – the sidebar on the right hand side in the editor. We’ll touch upon some new components that make sense to place in the sidebar and how to handle these.
- Part 6: Adding Toolbars
In this post we’ll learn how to add WordPress’ toolbars to our block, i.e. for alignment and block alignment. We will also learn to add our own toolbars with our own buttons for doing custom actions.
- Part 7: Creating Your Own Components
So far in this tutorial series we’ve written all code insideregisterBlockType()‘seditfunction. It’s fully possible, and often recommended to instead assign edit to a separate component. By doing so we can utilize functionality like component state and lifecycle methods.
- Part 8: Translation of your Block
In this part we’ll focus on how to translate the texts and values in our block. We use WP-CLI to generate the necessary files so that Gutenberg is able to load our translations when switching the WordPress language.
- Part 9: Dynamic Blocks
So far we have rendered the block’s output in Javascript. However with dynamic content like recent posts or displaying a post might require us to render the block’s output in PHP.
- Part 10: Fetching Posts and Higher-Order Components
In the final part we’ll learn how to use higher-order components, and thus how to perform a post query from within the editor and provide a method to select posts.