Block Editor Developer’s Guide
Draft. Last Updated:
Over the last year 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.
General Concepts
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).
Global Styles
Tools
theme.json- Site Editor
- Theme Stylesheets
Let’s start with global styles.
Styling Blocks
Tools
theme.json- Site Editor Block Styles
register_block_style- Theme Stylesheets
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.
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:
🎥 Custom Lists in WordPress with Register Block Style – Register a custom block style in Gutenberg with simple PHP and CSS- no JavaScript or build process required.
Extending Blocks
Tools
registerBlockVariation- Custom Block Attributes
render_block
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.
This simplest approach is via Block Variations.
🎥 Using Block Variations with the Block Bindings API – Dig into the new Block Bindings API in WordPress 6.5 – with a focus on how to offer a “no-code” experience for your users with Block Variations.
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.
Using the 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.
Building Blocks
Tools
registerBlockType- ACF Blocks
- Dynamic Blocks
<InnerBlocks />@wordpress/create-block@10up/block-extensions
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.
🎥 ACF Blocks Post Carousel Tutorial – We’re building a post carousel block using ACF Blocks. We’re doing everything from start to finish, including loading a third-party resource (Flickity) and default Gutenberg supports like colors and alignment. No build process, no fancy JavaScript, just Advanced Custom Fields.
Next up is my favorite method for building blocks: using other core blocks. Basically you register a block that has a pre-defined set of blocks inside of it. It’s sort of like a block pattern, but you have a little bit more control over it, like enqueuing your own stylesheet and JavaScript with it or even adding custom settings.
🎥 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
Tools
- Block Patterns
- Template Parts
- Templates
Once you’ve designed/built the mediumer 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.
Custom Themes
Tools
- Starter theme (coming soon)
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.
Custom Plugins
Tools
@wordpress/create-block@wordpress/scripts- SlotFills – Extending the Block Editor
For more advanced tasks- or to share resources across multiple themes- you might be building plugins.
Plugins often exist to modify the WordPress UI itself- adding settings pages or placing buttons, custom fields, or extra features inside the block editor. The first step is understanding the WordPress “Data Layer” – essentially all the JavaScript tooling that let you access and modify your WordPress data inside of the editor.
✏️ Recreating the Quick Draft dashboard widget using the WordPress Data Layer – The best way I can describe the data layer is to imagine having a complete UI framework of WordPress components- then combining that with a complete React.js/Redux JavaScript framework hand-tailored to the WordPress REST API.
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:
💻 bacoords/example-wp-settings – This is an example of a JavaScript and WP REST API-powered WordPress settings page.
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.
Other Resources
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.
- JS Essentials for WordPress Developers – A free video course covering the basics of JavaScript from a WP perspective.
What am I missing? Let me know by DMing me on Twitter, the Fediverse, or in the Make WordPress Slack.