Block Editor Developer’s Guide
Draft. Last Updated:
Over the last few months I’ve been creating a lot of tutorials about the WordPress block editor (Gutenberg). This page is my attempt to put all of those articles and videos into a context, maybe even a suggested flow towards leveling up your block editor development skills. I’ll continue to update it as I generate new content.
The first place I like to start is with core blocks and their built-in features, like typography controls, spacing, colors, etc. WordPress includes blocks for most important semantic elements- paragraphs, headings, buttons, etc- as well as structural elements like columns, rows, groups, and more. The more time you spend with core blocks, the more understand the mindset and current feature set of the editor.
That said, I know that the first major hurdle for new users are the concepts around alignment, containers, and width, especially if you come from the world of Page Builders, Bootstrap, or Tailwind. Here’s a run-down of content widths in Gutenberg:
✏️ “Normal” width websites in the block editor – What is going on with max-widths and alignments in the block editor? Is there a method behind this madness?
If you’d like to see those layout settings in practice, I built an example layout in the block editor and used it as an opportunity to cover alignments, widths, flex controls, semantic elements, and more.
🎥 Building an example layout in Gutenberg (response video) – Walkthrough video as I build a demo layout using core blocks and a few lines of CSS (via register_block_style).
When it comes to designing core blocks,
theme.json should always be the starting point. I’m continually surprised by what’s already possible with the block editor.
If you feel the urge to write some CSS, the next step is adding your own custom styles to existing blocks. You can do this in your theme’s stylesheet, but if you want to make those styles optional, you’ll want to register a Block Style. Here’s a quick look at how that’s done, no build process required:
Block styles are great, but they’re limiting. You can only apply one style to a block at a time, and you might end up with so many choices that the default UI (a big stack of buttons) doesn’t really work. That’s when we move into extending core blocks.
First, let’s take a look at adding a custom field to a core block, then using that information to modify the block’s content and design before it is rendered on the page:
🎥 Adding Custom Fields (Attributes) to Core Blocks – Using just three filters, we’ll add a few custom fields to the core “Button” block in WordPress that will update the button’s content on the front end.
render_block filter in WordPress is one of the safest ways to update block content before it hits the screen- without modifying what happens in the editor. Here’s another quick tutorial on modifying the contents of a block before it is rendered:
✏️ Filter the URLs in Gutenberg Social Link Block – Dynamically populate social link URLs using the render_block filter in WordPress.
If you can’t make what you need by adding CSS to core blocks, you might need to build a custom block. There’s a few ways to go about this, so let’s start with the more common, perhaps more simple approach: ACF Blocks. Here’s a tutorial to get you starting building a block with ACF.
🎥 Build Custom Blocks Using InnerBlocks – A great way to start building blocks for WordPress is using InnerBlocks. Group other blocks together and easily add styles and settings.
Another popular type of block is the dynamic block. The benefit here is that your block’s frontend is written in PHP, which gives you full access to WordPress’s PHP functionality and means that the block can be updated more easily.
🎥 How to Build Dynamic (PHP) Blocks in WordPress – Let’s build a custom WordPress block with a focus on Let’s build a dynamic block for WordPress. Along the way we’ll discuss the difference between static and dynamic blocks, when to use them, WP_Query, what ServerSideRender is and what the best approach for performance is.
- Developer Docs: Static vs. dynamic blocks
Finally, you might need to make a block entirely from scratch. Not to worry, there’s still plenty of scaffolding to help you build your block, from WordPress’ core component library, to 3rd party packages like 10up’s Block Components. Here we build a custom block around one of the trickier tasks in WordPress, working with Media/Attachment Images.
🎥 Managing Images in your Custom Gutenberg Block – Let’s build a custom WordPress block with a focus on editable image fields. Using the block-components library from 10up and a custom image function I wrote this year, we’ll go through every file in our custom block together.
Templates and Patterns
Once you’ve designed/built the smaller elements (blocks), you’ll want to combine them into patterns, and combine those patterns into templates. This section is in progress, but mostly I’m waiting for WordPress 6.5 to finish a few things around patterns.
If you’ve made it this far, there’s a good chance you’re someone who makes custom themes from time to time. I have a lot more to say about this, especially as Full Site Editing reaches maturity.
For now, though, I just have one tutorial in the theme category which shows how to enable the “Choose a Pattern” modal when you start a new post/page/CPT.
✏️ How to show the “Choose a Pattern” modal by default on new pages – How to offer a selection of page patterns when creating a new page (as seen in TwentyTwentyFour).
That tutorial is part of the larger idea in WordPress, which is: curating the editorial experience.
For more advanced tasks- or to share resources across multiple themes- you might be building plugins.
Maybe you’re writing a plugin and you need a settings page. I’m working on a tutorial that discusses settings pages that use WordPress core’s React components and REST API. In the meantime, you can browse repo for it here:
If you’re looking to add custom fields to posts (or pages or any custom post type). I’ve set up an example repo with a custom field:
💻 bacoords/example-post-settings-field – Add a custom field to posts in the block editor sidebar.
And finally, here’s an older example of adding custom information to the “post-publish” panel (that’s the sidebar that shows up after you’ve clicked “Publish” on a post).
✏️ Hooking into the Block Editor’s Post Publish Panel (with Copilot) – A walkthrough of Copilot and I attempting to add some content to the post-publish panel in the block editor.
There’s plenty of good stuff out there beyond the core documentation, but I’ll list a few things I can recommend.
- WordPress Developer Blog – Subscribe or search the archives for a specific topic, the Developer Blog is putting out great content.
- Aurooba Makes Courses – Handy course on Thoughtful UI for the Block Editor
- Building a Custom Accordion In React – On our podcast, Aurooba and I go from the basics of React to building a custom accordion element. There’s also episodes on building custom blocks vs ACF blocks, and other WordPress stuff.