๐ Letโs Connect! Follow me on GitHub for new projects and tips.
Introduction
Gutenberg, the block editor introduced in WordPress 5.0, has completely reshaped how developers build content and interfaces in WordPress. Instead of relying on shortcodes or custom metaboxes, Gutenberg uses a modular system of blocksโeach representing a piece of content or functionality. With full-site editing (FSE) and advancements in block-based themes, understanding Gutenberg is crucial for modern WordPress development.
This article walks through the basics of Gutenberg development, including static and dynamic blocks, using @wordpress/create-block
, theming approaches, and key tools for building block-based experiences.
What is Gutenberg?
Gutenberg is the code name for the WordPress block editor. It replaces the classic TinyMCE editor with a visual block-based system, allowing users to create rich layouts without writing HTML or using custom fields.
Understanding Blocks
What is a Block?
A block is a single piece of contentโsuch as a paragraph, image, gallery, heading, or custom functionality. Each block is a React component under the hood, managed via the WordPress Block Editor.
There are two major types:
- Static Blocks: Rendered entirely on the client side.
- Dynamic Blocks: Rendered on the server via PHP.
Creating Blocks with @wordpress/create-block
The easiest way to scaffold a custom block is with the official tool:
npx @wordpress/create-block my-custom-block
This will set up a WordPress plugin with:
- Block registration
- Block.json configuration
- React-based editor component
- Webpack build process (via wp-scripts)
Example: A Basic Static Block
block.json
{
"apiVersion": 2,
"name": "myplugin/hello-block",
"title": "Hello Block",
"category": "widgets",
"editorScript": "file:./index.js"
}
index.js
import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps } from '@wordpress/block-editor';
registerBlockType('myplugin/hello-block', {
edit() {
return <div {...useBlockProps()}>Hello from the editor!</div>;
},
save() {
return <div {...useBlockProps.save()}>Hello on the frontend!</div>;
}
});
Dynamic Blocks: When You Need PHP
For server-rendered content, dynamic blocks use a render_callback
in PHP:
PHP Registration Example
function register_dynamic_block() {
register_block_type( __DIR__ . '/build', [
'render_callback' => 'render_my_dynamic_block',
]);
}
add_action( 'init', 'register_dynamic_block' );
function render_my_dynamic_block( $attributes ) {
return '<div class="dynamic-block">Generated at ' . date('H:i:s') . '</div>';
}
Dynamic blocks are useful for:
- Data from the database
- Third-party API calls
- Secure or complex logic that shouldn't be in the client
Editor APIs and Helpers
-
useBlockProps()
โ Adds proper attributes and classes -
InspectorControls
โ Adds settings in the sidebar -
RichText
โ Editable text field -
MediaUpload
โ Upload/choose media files -
InnerBlocks
โ Allow nested blocks (great for layout components)
Theming with Gutenberg
Classic Theme Approach
Older themes required add_theme_support()
and often needed custom editor styles.
add_theme_support( 'editor-styles' );
add_editor_style( 'editor-style.css' );
Block support could be selectively added:
add_theme_support( 'align-wide' );
add_theme_support( 'editor-color-palette', [ /* colors */ ] );
Modern Block Themes (FSE)
With Full Site Editing, themes are built using:
-
theme.json
for global styles -
templates/
andparts/
folders - No traditional PHP templates for layout
theme.json
example
{
"version": 2,
"settings": {
"color": {
"palette": [ { "name": "Black", "slug": "black", "color": "#000000" } ]
},
"spacing": {
"padding": true
}
}
}
Full-site editing enables users to edit headers, footers, and other layout areas directly in the block editor.
Useful Tools and Resources
-
@wordpress/scripts
: Handles build configuration -
@wordpress/components
: Pre-styled UI components -
@wordpress/data
: Access and manage editor state - Block Editor Handbook
- Theme Developer Handbook
Key Takeaways
โ Gutenberg replaces traditional WordPress editing with a React-powered block system
โ Use @wordpress/create-block
to scaffold static or dynamic blocks
โ Static blocks use JavaScript for frontend rendering; dynamic blocks use PHP
โ Classic themes still work but modern block themes use theme.json
and FSE templates
โ Custom blocks enhance UX and site flexibility for developers and users alike
Conclusion
Gutenberg has transformed the WordPress ecosystem from a document-based CMS to a modern visual builder with developer-friendly APIs. Whether you're building a small site or a complex editor experience, learning how to create custom blocks and block themes will future-proof your WordPress skills.
Are you building with Gutenberg already? Whatโs your favorite block youโve created?
Meta Description
Learn the basics of WordPress Gutenberg developmentโblocks, dynamic blocks, theming, and block editor APIsโusing modern tools like @wordpress/create-block
.
TLDR โ Highlights for Skimmers
- WordPress uses blocks instead of shortcodes or metaboxes
- Use
npx @wordpress/create-block
to scaffold custom blocks - Static blocks use JS; dynamic blocks use PHP rendering
- Classic themes use
functions.php
; modern themes usetheme.json
- Full Site Editing (FSE) makes the entire theme editable with blocks
Let me know what Gutenberg block youโre building in the comments below!
Top comments (4)
So cool ๐
I've never been able to connect with WordPress, it's really hard for me to buy plugins or check files repeatedly for errors.๐ค๐๐ญ๐ญ
Hi Vida ๐
I prefer working outside of WordPress, but it can be a fantastic tool for certain needs. Gutenberg has really helped make it more extendable over the years.
That said, for anyone who comes across this comment and hasn't seen Vida's work - please check out dev.to/vidakhoshpey22/nebula-works...
Nicely done!
Oh thank you so much๐, you make me motivated even though it's a simple site. And it's so good , I wish I could use Wordpress too . It's like WordPress is an enemy to me, haha, I feel like I can't understand it, I understand Django or the code in front of me, but WordPress, which they say is soooo easy, has always been a problem.๐๐ญ
Anything cool or experimental you've found you can do with blocks of late?