You already know how to build a classic WordPress theme. You have your header.php, your footer.php, and the Loop wired into your bones. But the block editor changed the game. Full Site Editing (FSE) and block themes now let you design layouts, templates, and styles using the same editor your clients use for content. If you want to stay current in 2026, learning to create a custom WordPress theme with the block editor is the skill that sets you apart. This guide walks you through the entire process, from scaffolding the project to shipping a production-ready theme.
Building a block theme means you define templates, styles, and patterns inside the block editor itself, not in separate PHP template files. You will create a theme.json file for global styles, use HTML template files with block markup, and register custom block patterns. This approach reduces PHP code, improves maintainability, and gives your clients a consistent editing experience. The result is a leaner, faster theme that aligns with WordPress’s modern development standards.
What You Need Before You Start
Before you write any code, set up your local environment. You need a WordPress installation running version 6.0 or later (ideally the latest 2026 release). Use a tool like Local or DevKinsta to spin up a test site. You also need a code editor and a basic understanding of HTML, CSS, and JSON.
Make sure you have a block theme enabled as your default theme. The default Twenty Twenty-Six theme is a good reference. You can peek at its files to understand the structure, but you will build your own from scratch.
The Core File Structure of a Block Theme
A block theme has a simpler file structure than a classic theme. You do not need header.php, footer.php, or sidebar.php. Instead, you use HTML files with block markup. Here is the minimum you need:
my-block-theme/
|-- style.css
|-- theme.json
|-- index.php
|-- templates/
| |-- index.html
| |-- single.html
| |-- archive.html
|-- parts/
| |-- header.html
| |-- footer.html
|-- patterns/
|-- assets/
|-- css/
|-- js/
The style.css file still holds the theme header comment. The theme.json file replaces functions.php for most global styling and settings. Templates live in the templates folder, and reusable parts like headers and footers live in the parts folder.
Step 1: Scaffold Your Theme
Create a new folder inside wp-content/themes/ and name it something unique, like my-block-theme. Inside that folder, create a style.css file with the required theme header:
/*
Theme Name: My Block Theme
Theme URI: https://example.com
Author: Your Name
Description: A custom block theme built from scratch.
Version: 1.0.0
License: GPL v2
Text Domain: my-block-theme
*/
That is all you need for WordPress to recognize your theme. Next, create the templates and parts folders. Your theme will not do anything yet, but it will appear in the admin under Appearance > Themes.
Step 2: Configure Global Styles with theme.json
The theme.json file is the heart of your block theme. It controls colors, typography, spacing, and layout settings across your entire site. Instead of writing CSS for every element, you define design tokens here.
Here is a minimal theme.json to get started:
{
"version": 2,
"settings": {
"layout": {
"contentSize": "800px",
"wideSize": "1200px"
},
"color": {
"palette": [
{ "slug": "primary", "color": "#1a73e8", "name": "Primary" },
{ "slug": "secondary", "color": "#34a853", "name": "Secondary" },
{ "slug": "background", "color": "#ffffff", "name": "Background" },
{ "slug": "foreground", "color": "#1a1a2e", "name": "Foreground" }
]
},
"typography": {
"fontFamilies": [
{ "fontFamily": "Inter", "slug": "inter", "name": "Inter" }
],
"fontSizes": [
{ "name": "Small", "slug": "small", "size": "14px" },
{ "name": "Medium", "slug": "medium", "size": "18px" },
{ "name": "Large", "slug": "large", "size": "24px" }
]
}
}
}
This file defines your color palette, font options, and content widths. The block editor uses these values to populate the global styles panel. Your clients will see these exact options when they customize the site.
Step 3: Build Your First Template File
Templates in a block theme are HTML files that contain block markup. You write them using the same blocks your clients use in the editor. Open your templates/index.html file and add this:
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
<!-- wp:post-title {"level":1} /-->
<!-- wp:post-content /-->
</div>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
This template uses three blocks: a template part for the header, a group block to contain the main content, and a template part for the footer. The post-title and post-content blocks pull in the actual page or post data.
Now create parts/header.html:
<!-- wp:group {"tagName":"header","style":{"spacing":{"padding":{"top":"20px","bottom":"20px"}}}} -->
<header class="wp-block-group">
<!-- wp:site-title /-->
<!-- wp:navigation /-->
</header>
<!-- /wp:group -->
And parts/footer.html:
<!-- wp:group {"tagName":"footer","style":{"spacing":{"padding":{"top":"20px","bottom":"20px"}}}} -->
<footer class="wp-block-group">
<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">Copyright 2026 My Block Theme</p>
<!-- /wp:paragraph -->
</footer>
<!-- /wp:group -->
Activate your theme in the WordPress admin. Your homepage should now display the site title, a navigation area, and a footer. You just built a functional block theme with fewer than 20 lines of markup.
Step 4: Register Custom Block Patterns
Block patterns let you bundle multiple blocks into reusable layouts. They are perfect for common sections like hero banners, testimonials, or pricing tables. Create a file inside the patterns/ folder, for example hero-pattern.html:
<!-- wp:cover {"overlayColor":"primary","minHeight":400} -->
<div class="wp-block-cover" style="min-height:400px">
<span class="wp-block-cover__background has-primary-background-color"></span>
<div class="wp-block-cover__inner-container">
<!-- wp:heading {"textAlign":"center","level":1} -->
<h1 class="has-text-align-center">Welcome to Our Site</h1>
<!-- /wp:heading -->
<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">A modern block theme built for you.</p>
<!-- /wp:paragraph -->
<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
<div class="wp-block-buttons">
<!-- wp:button {"backgroundColor":"secondary"} -->
<div class="wp-block-button">
<a class="wp-block-button__link has-secondary-background-color">Get Started</a>
</div>
<!-- /wp:button -->
</div>
<!-- /wp:buttons -->
</div>
</div>
<!-- /wp:cover -->
To register this pattern, add a patterns directory to your theme and include a manifest.json file, or simply use the register_block_pattern function in a small plugin. WordPress 6.6 and later also support registering patterns directly from the patterns folder.
Step 5: Add Custom CSS and JavaScript
Even though block themes rely on theme.json for global styles, you still need custom CSS for specific design tweaks. Create a style.css file inside your assets/css/ folder and enqueue it. The best way is to add a functions.php file with a minimal enqueue function:
<?php
function my_block_theme_assets() {
wp_enqueue_style( 'my-block-theme', get_template_directory_uri() . '/assets/css/style.css' );
}
add_action( 'wp_enqueue_scripts', 'my_block_theme_assets' );
Keep your CSS lean. Block themes handle most layout and spacing through the editor. Use CSS only for hover states, animations, or brand-specific details that theme.json cannot express.
Common Pitfalls and How to Avoid Them
Even experienced developers stumble on a few key areas when building block themes. Here is a table of the most frequent mistakes and their solutions:
| Mistake | Why It Happens | The Fix |
|---|---|---|
| Missing theme.json | Theme loads but has no styling. | Always include a valid theme.json with version 2. |
| HTML block markup with wrong comments | Blocks do not render. | Use <!-- wp:blockname /--> syntax exactly. |
| Forgetting to close block comments | Editor shows raw code. | Every <!-- wp:... --> needs a matching <!-- /wp:... -->. |
| No index.html template | Homepage shows a white screen. | Create templates/index.html as your fallback. |
| Overriding theme.json with CSS | Styles conflict with editor. | Use theme.json for defaults, CSS only for exceptions. |
A block theme is not just a new way to build. It is a contract between you and the editor. When you define styles in
theme.json, the editor respects them. When you override them in CSS, the editor may not reflect those changes. Keep your style definitions in the right place.
When to Use a Child Theme
If you are modifying an existing block theme, consider creating a child theme instead of editing the parent files. The process is similar to classic child themes. Create a style.css with a Template header pointing to the parent theme. You can then override specific template files or add new patterns without touching the original code. This approach is safer for client projects where updates to the parent theme might conflict with your customizations. For a deeper look at this workflow, read our guide on child themes explained: when you need one and how to create it safely.
Testing Your Block Theme
Before you deploy, test your theme in a few key areas:
- Activate the theme and check every default template (index, single, archive, page).
- Use the block editor to create a new post. Verify that your styles, colors, and font options appear in the settings panel.
- Test responsiveness on a mobile viewport. Your
theme.jsonlayout settings should handle most breakpoints, but verify with actual devices. - Run a performance check. Block themes tend to be lighter, but bloated CSS or large pattern files can slow things down. Use a tool like PageSpeed Insights to confirm.
If you notice layout issues, review your theme.json settings and template markup. The 5 signs your WordPress theme is slowing down your website guide can help you spot performance red flags early.
Your Next Steps With Block Themes
Building a custom WordPress theme with the block editor is a shift in mindset. You move from writing PHP loops to composing HTML block markup. You replace customizer settings with a single theme.json file. The payoff is a theme that is easier to maintain, faster to build, and more intuitive for your clients to edit.
Start with a simple two-template theme. Add a custom pattern. Experiment with theme.json until you feel comfortable. Within a few projects, you will wonder why you ever built themes any other way. If you run into issues, the 5 fixes for broken CSS after a WordPress update article can help you troubleshoot style conflicts.
Now open your code editor and scaffold that first block theme. You have everything you need to build something modern, lean, and completely your own.