WordPress Full Site Editing (FSE) has fundamentally changed how developers and site owners build WordPress websites. If you have been relying on the Classic Editor or traditional PHP theme development, this wordpress full site editing tutorial will walk you through everything you need to know to master FSE in 2026 — from core concepts to advanced template customization, theme.json configuration, and building production-ready block themes.
Since WordPress 5.9 introduced Full Site Editing, the platform has matured significantly. With WordPress 6.7+ and the upcoming 7.0 release, FSE is no longer experimental — it is the standard way to build modern WordPress themes. This guide covers every aspect of FSE development, with practical code examples and step-by-step instructions you can apply to your projects immediately.
WordPress Full Site Editing (FSE) is a collection of features that extends the Gutenberg block editor beyond post and page content to the entire site structure. Instead of editing just the content area, FSE allows you to visually design and customize headers, footers, sidebars, archive pages, 404 pages, and every other template your site uses — all through the familiar block editor interface.
At its core, FSE consists of four main components that work together to provide a complete site-building experience:
- Site Editor — The visual interface for editing all templates and template parts (Appearance > Editor)
- Block Themes — Themes built entirely with blocks and HTML templates instead of PHP template files
- Global Styles — A centralized system for managing typography, colors, spacing, and layout across your entire site
- theme.json — The configuration file that defines your theme’s settings, styles, and block defaults
Together, these components replace the traditional WordPress Customizer, widget areas, menu management screens, and much of the PHP template hierarchy with a unified, block-based approach to site building. For an in-depth look at how these components fit together, refer to the official WordPress Full Site Editing documentation.
“Full Site Editing represents the next evolution of WordPress — giving every user the power to customize their entire site visually, without writing a single line of code. It is about democratizing not just publishing, but design itself.”
— Matt Mullenweg, WordPress co-founder, State of the Word 2023
Before diving into the technical details, it is important to understand what separates a block theme from a classic theme. The differences affect how you build, customize, and maintain WordPress sites.
| Feature | Classic Themes | Block Themes (FSE) |
|---|---|---|
| Template files | PHP (header.php, footer.php, single.php) | HTML with block markup (.html files) |
| Customization | Customizer, widgets, menus | Site Editor with blocks |
| Styling control | style.css + PHP functions | theme.json + Global Styles UI |
| Header/Footer editing | Code editing required | Visual drag-and-drop |
| Template hierarchy | PHP template hierarchy | HTML template hierarchy (same naming) |
| Widget areas | register_sidebar() + widgets | Template parts with blocks |
| Navigation menus | wp_nav_menu() + Menus screen | Navigation block in Site Editor |
| Learning curve | PHP, WordPress APIs | Block editor, theme.json, JSON |
| User empowerment | Limited to Customizer options | Full visual control over every element |
The fundamental shift is from code-first to visual-first. While classic themes require PHP knowledge to modify layouts, block themes allow visual editing of every element. This is a separate paradigm from headless WordPress development, which decouples the frontend entirely. However, developers still have full control through theme.json and custom block patterns — the approach is different, but the power remains.
Setting Up Your First Block Theme
Building a block theme from scratch is the best way to understand how FSE works under the hood. A minimal block theme requires surprisingly few files compared to a classic theme. Here is the essential file structure:
my-fse-theme/
├── style.css # Theme metadata (required)
├── theme.json # Theme configuration (required)
├── templates/
│ ├── index.html # Main fallback template (required)
│ ├── single.html # Single post template
│ ├── page.html # Page template
│ ├── archive.html # Archive template
│ ├── 404.html # 404 error template
│ ├── search.html # Search results template
│ └── home.html # Blog posts page
├── parts/
│ ├── header.html # Header template part
│ ├── footer.html # Footer template part
│ └── sidebar.html # Sidebar template part
└── patterns/
├── hero-section.php # Reusable block pattern
└── cta-banner.php # Call-to-action patternThe minimum viable block theme needs just three files: style.css (with the theme header comment), theme.json, and templates/index.html. Everything else is optional but recommended for a complete theme.
The style.css Theme Header
The style.css file in a block theme serves primarily as a metadata declaration. Unlike classic themes where style.css contains all your CSS rules, a block theme’s styling is largely handled by theme.json:
/*
Theme Name: My FSE Theme
Theme URI: https://example.com/my-fse-theme
Author: Your Name
Author URI: https://example.com
Description: A modern block theme built with Full Site Editing.
Version: 1.0.0
Requires at least: 6.4
Tested up to: 6.7
Requires PHP: 8.0
License: GNU General Public License v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-fse-theme
*/The theme.json file is the most important file in any block theme. It controls global settings, defines your design tokens (colors, fonts, spacing), configures block-level defaults, and determines what customization options are available to users. Understanding theme.json deeply is essential for any wordpress full site editing tutorial. For the definitive reference, consult the WordPress Global Settings and Styles documentation, which covers every property and its valid values.
Complete theme.json Structure
Here is a production-ready theme.json configuration that demonstrates the major capabilities:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"appearanceTools": true,
"layout": {
"contentSize": "800px",
"wideSize": "1200px"
},
"color": {
"palette": [
{ "slug": "primary", "color": "#1e40af", "name": "Primary" },
{ "slug": "secondary", "color": "#7c3aed", "name": "Secondary" },
{ "slug": "accent", "color": "#059669", "name": "Accent" },
{ "slug": "base", "color": "#ffffff", "name": "Base" },
{ "slug": "contrast", "color": "#1a1a2e", "name": "Contrast" },
{ "slug": "neutral", "color": "#f3f4f6", "name": "Neutral" }
],
"gradients": [
{
"slug": "primary-to-secondary",
"gradient": "linear-gradient(135deg, #1e40af 0%, #7c3aed 100%)",
"name": "Primary to Secondary"
}
]
},
"typography": {
"fluid": true,
"fontFamilies": [
{
"slug": "heading",
"name": "Heading",
"fontFamily": "'Inter', sans-serif",
"fontFace": [
{
"fontFamily": "Inter",
"fontWeight": "700",
"fontStyle": "normal",
"src": ["file:./assets/fonts/inter-bold.woff2"]
}
]
},
{
"slug": "body",
"name": "Body",
"fontFamily": "'Source Sans 3', sans-serif",
"fontFace": [
{
"fontFamily": "Source Sans 3",
"fontWeight": "400",
"fontStyle": "normal",
"src": ["file:./assets/fonts/source-sans-regular.woff2"]
}
]
}
],
"fontSizes": [
{ "slug": "small", "size": "0.875rem", "name": "Small" },
{ "slug": "medium", "size": "1rem", "name": "Medium" },
{ "slug": "large", "size": "1.25rem", "name": "Large" },
{ "slug": "x-large", "size": "1.75rem", "name": "Extra Large" },
{ "slug": "xx-large", "size": "2.5rem", "name": "Huge" }
]
},
"spacing": {
"units": ["px", "rem", "em", "%", "vw"],
"spacingSizes": [
{ "slug": "10", "size": "0.5rem", "name": "XS" },
{ "slug": "20", "size": "1rem", "name": "Small" },
{ "slug": "30", "size": "1.5rem", "name": "Medium" },
{ "slug": "40", "size": "2rem", "name": "Large" },
{ "slug": "50", "size": "3rem", "name": "XL" },
{ "slug": "60", "size": "5rem", "name": "XXL" }
]
},
"blocks": {
"core/button": {
"border": { "radius": true }
},
"core/code": {
"typography": {
"fontFamilies": [
{
"slug": "mono",
"name": "Monospace",
"fontFamily": "'JetBrains Mono', 'Fira Code', monospace"
}
]
}
}
}
},
"styles": {
"color": {
"background": "var(--wp--preset--color--base)",
"text": "var(--wp--preset--color--contrast)"
},
"typography": {
"fontFamily": "var(--wp--preset--font-family--body)",
"fontSize": "var(--wp--preset--font-size--medium)",
"lineHeight": "1.7"
},
"spacing": {
"blockGap": "1.5rem"
},
"elements": {
"heading": {
"typography": {
"fontFamily": "var(--wp--preset--font-family--heading)",
"fontWeight": "700",
"lineHeight": "1.2"
},
"color": {
"text": "var(--wp--preset--color--contrast)"
}
},
"link": {
"color": {
"text": "var(--wp--preset--color--primary)"
},
":hover": {
"color": {
"text": "var(--wp--preset--color--secondary)"
}
}
},
"button": {
"color": {
"background": "var(--wp--preset--color--primary)",
"text": "var(--wp--preset--color--base)"
},
"border": {
"radius": "6px"
},
"typography": {
"fontWeight": "600"
}
}
},
"blocks": {
"core/code": {
"color": {
"background": "#1a1a2e",
"text": "#e2e8f0"
},
"border": {
"radius": "8px"
},
"spacing": {
"padding": {
"top": "1.5rem",
"right": "1.5rem",
"bottom": "1.5rem",
"left": "1.5rem"
}
}
},
"core/separator": {
"color": {
"text": "var(--wp--preset--color--neutral)"
}
}
}
},
"templateParts": [
{ "name": "header", "title": "Header", "area": "header" },
{ "name": "footer", "title": "Footer", "area": "footer" }
],
"customTemplates": [
{ "name": "blank", "title": "Blank", "postTypes": ["page", "post"] },
{ "name": "landing-page", "title": "Landing Page", "postTypes": ["page"] }
]
}Key theme.json Concepts Explained
Let us break down the critical sections of theme.json and why each matters:
- Version — Always use version 3 (introduced in WordPress 6.6). It provides the latest schema features and better CSS custom property generation.
- appearanceTools — Setting this to
trueenables border, margin, padding, block gap, link color, and typography controls in the editor. It is a shortcut that avoids enabling each tool individually. - Layout sizes —
contentSizedefines the default content width, andwideSizedefines the wide alignment width. These create the layout constraints for your content area. - Fluid typography — Setting
"fluid": trueenables responsive font sizes that scale smoothly between viewport widths, eliminating the need for media queries in most typography scenarios. - Spacing presets — Define consistent spacing tokens that users can select from dropdowns, ensuring design consistency without manual pixel values.
- Block-level settings — Override global settings for specific blocks. In the example above, the code block gets a custom font family and dark background styling.
Building Templates with the Site Editor
The Site Editor (Appearance > Editor) is where you visually build and modify your site templates. Templates in FSE follow the same hierarchy as classic WordPress themes — index, single, page, archive, category, tag, author, search, and 404 — but they are stored as HTML files containing block markup instead of PHP.
Creating a Custom Single Post Template
Here is an example of a well-structured single post template (templates/single.html) that demonstrates key FSE template concepts:
<!-- wp:template-part {"slug":"header","area":"header"} /-->
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
<!-- wp:group {"style":{"spacing":{"padding":{"top":"var:preset|spacing|50","bottom":"var:preset|spacing|30"}}}} -->
<div class="wp-block-group" style="padding-top:var(--wp--preset--spacing--50);padding-bottom:var(--wp--preset--spacing--30)">
<!-- wp:post-title {"level":1,"style":{"typography":{"fontSize":"2.5rem"}}} /-->
<!-- wp:group {"layout":{"type":"flex","flexWrap":"nowrap"},"style":{"spacing":{"blockGap":"1rem"}}} -->
<div class="wp-block-group">
<!-- wp:post-date /-->
<!-- wp:post-author {"showAvatar":false} /-->
<!-- wp:post-terms {"term":"category"} /-->
</div>
<!-- /wp:group -->
</div>
<!-- /wp:group -->
<!-- wp:post-featured-image {"aspectRatio":"16/9","style":{"border":{"radius":"12px"}}} /-->
<!-- wp:post-content {"layout":{"type":"constrained"}} /-->
<!-- wp:separator {"className":"is-style-wide"} -->
<hr class="wp-block-separator is-style-wide"/>
<!-- /wp:separator -->
<!-- wp:post-terms {"term":"post_tag","prefix":"Tags: "} /-->
<!-- wp:comments /-->
</main>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","area":"footer"} /-->Notice how template parts are referenced by their slug (header, footer). The post-content block renders the actual post content, while blocks like post-title, post-date, post-author, and post-terms dynamically pull data from the post being displayed. This is the FSE equivalent of calling PHP functions like the_title() and the_content() in classic themes.
Creating Template Parts
Template parts are reusable sections that can be included in multiple templates. The most common are header and footer. Here is a modern header template part (parts/header.html):
<!-- wp:group {"style":{"spacing":{"padding":{"top":"1rem","bottom":"1rem"}}},"backgroundColor":"contrast","textColor":"base","layout":{"type":"constrained"}} -->
<div class="wp-block-group has-base-color has-contrast-background-color has-text-color has-background" style="padding-top:1rem;padding-bottom:1rem">
<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
<div class="wp-block-group">
<!-- wp:site-title {"style":{"typography":{"fontWeight":"700"}}} /-->
<!-- wp:navigation {"layout":{"type":"flex","justifyContent":"right"}} /-->
</div>
<!-- /wp:group -->
</div>
<!-- /wp:group -->Block patterns are predefined block arrangements that users can insert with a single click. They are one of the most powerful features in FSE for creating consistent, professional designs without writing code. Patterns are stored as PHP files in your theme’s patterns/ directory.
Creating a Custom Block Pattern
Here is an example of a hero section pattern (patterns/hero-section.php):
<?php
/**
* Title: Hero Section
* Slug: my-fse-theme/hero-section
* Description: A full-width hero section with heading, text, and CTA buttons.
* Categories: featured, banner
* Keywords: hero, banner, cta, landing
* Viewport Width: 1200
* Block Types: core/cover
*/
?>
<!-- wp:cover {"overlayColor":"contrast","minHeight":500,"isDark":true,"align":"full","style":{"spacing":{"padding":{"top":"var:preset|spacing|60","bottom":"var:preset|spacing|60"}}}} -->
<div class="wp-block-cover alignfull is-dark" style="padding-top:var(--wp--preset--spacing--60);padding-bottom:var(--wp--preset--spacing--60);min-height:500px">
<span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim-100 has-background-dim"></span>
<div class="wp-block-cover__inner-container">
<!-- wp:heading {"textAlign":"center","level":1,"style":{"typography":{"fontSize":"3.5rem","fontWeight":"800"}},"textColor":"base"} -->
<h1 class="has-text-align-center has-base-color has-text-color" style="font-size:3.5rem;font-weight:800">Build Beautiful WordPress Sites</h1>
<!-- /wp:heading -->
<!-- wp:paragraph {"align":"center","style":{"typography":{"fontSize":"1.25rem"}},"textColor":"neutral"} -->
<p class="has-text-align-center has-neutral-color has-text-color" style="font-size:1.25rem">Create stunning, responsive websites with the power of Full Site Editing and block themes.</p>
<!-- /wp:paragraph -->
<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"},"style":{"spacing":{"margin":{"top":"2rem"}}}} -->
<div class="wp-block-buttons" style="margin-top:2rem">
<!-- wp:button {"backgroundColor":"primary","style":{"border":{"radius":"8px"}}} -->
<div class="wp-block-button"><a class="wp-block-button__link has-primary-background-color has-background wp-element-button" style="border-radius:8px">Get Started</a></div>
<!-- /wp:button -->
<!-- wp:button {"className":"is-style-outline"} -->
<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button">Learn More</a></div>
<!-- /wp:button -->
</div>
<!-- /wp:buttons -->
</div>
</div>
<!-- /wp:cover -->The PHP file header comments are parsed by WordPress to register the pattern automatically. The Categories field determines where the pattern appears in the inserter, and Keywords helps users find it through search. This auto-registration feature (introduced in WordPress 6.0) eliminates the need for manual register_block_pattern() calls.
Global Styles: Centralized Design Control
Global Styles is the visual interface for theme.json. It allows site owners to modify colors, typography, spacing, and layout settings without writing any code or JSON. Changes made through Global Styles are stored in the database and override the theme’s theme.json defaults.
To access Global Styles, open the Site Editor and click the half-moon icon (Styles) in the top-right toolbar. From there, you can customize:
- Typography — Change fonts, sizes, line heights, and letter spacing for headings, body text, links, and buttons
- Colors — Modify the theme’s color palette, background, text, and link colors
- Layout — Adjust content width, wide width, and block gap spacing
- Per-block styles — Customize the default appearance of any specific block type
- Style variations — Switch between pre-designed style presets that change multiple settings at once
Pro tip: Use Global Styles style variations to offer users multiple pre-designed looks for your theme. Create alternative JSON files in your theme’s
styles/directory (e.g.,styles/dark-mode.json,styles/warm-palette.json). Each file contains only the settings and styles that differ from your base theme.json.
FSE introduces several theme-specific blocks that are critical for building dynamic templates. Understanding these blocks is fundamental to any wordpress full site editing tutorial:
| Block | Purpose | Used In |
|---|---|---|
| Site Title | Displays the site name dynamically | Header template part |
| Site Logo | Shows the site logo from Customizer settings | Header template part |
| Navigation | Renders site navigation menus with responsive mobile toggle | Header template part |
| Query Loop | Displays a list of posts based on query parameters | Archive, home, search templates |
| Post Template | Defines the layout for each post within a Query Loop | Inside Query Loop |
| Post Title | Renders the post/page title | Single, page templates |
| Post Content | Renders the post/page content | Single, page templates |
| Post Featured Image | Displays the featured image | Single, archive templates |
| Post Date | Shows the publish date | Single, archive templates |
| Post Author | Displays author name and optionally avatar | Single templates |
| Post Terms | Shows categories, tags, or custom taxonomy terms | Single, archive templates |
| Post Excerpt | Renders the excerpt or auto-generated summary | Archive, search templates |
| Template Part | Includes a reusable template part | All templates |
| Post Navigation Link | Previous/Next post navigation | Single templates |
The Query Loop Block: Deep Dive
The Query Loop block is arguably the most powerful FSE block. It replaces the traditional WordPress Loop (the while ( have_posts() ) PHP construct) with a visual, configurable block. You can filter by post type, category, tag, author, keyword, and more — all without writing a single line of PHP.
Here is a Query Loop configuration for displaying the latest 6 posts in a 3-column grid layout with featured images and excerpts:
<!-- wp:query {"queryId":1,"query":{"perPage":6,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"exclude","inherit":false},"displayLayout":{"type":"flex","columns":3}} -->
<div class="wp-block-query">
<!-- wp:post-template {"layout":{"type":"grid","columnCount":3}} -->
<!-- wp:post-featured-image {"isLink":true,"aspectRatio":"16/9","style":{"border":{"radius":"8px"}}} /-->
<!-- wp:post-title {"isLink":true,"level":3,"style":{"typography":{"fontSize":"1.2rem"}}} /-->
<!-- wp:post-excerpt {"moreText":"Read More","excerptLength":20} /-->
<!-- wp:post-date {"style":{"typography":{"fontSize":"0.85rem"}},"textColor":"neutral"} /-->
<!-- /wp:post-template -->
<!-- wp:query-pagination {"layout":{"type":"flex","justifyContent":"center"}} -->
<!-- wp:query-pagination-previous /-->
<!-- wp:query-pagination-numbers /-->
<!-- wp:query-pagination-next /-->
<!-- /wp:query-pagination -->
<!-- wp:query-no-results -->
<!-- wp:paragraph -->
<p>No posts found. Try adjusting your search or filter.</p>
<!-- /wp:paragraph -->
<!-- /wp:query-no-results -->
</div>
<!-- /wp:query -->Advanced FSE Techniques for 2026
With WordPress 6.7 and the upcoming 7.0, FSE has gained several advanced features that make it viable for complex, enterprise-grade sites. The development progress can be tracked on the WordPress Core development blog, where contributors share updates on Gutenberg and FSE milestones. Here are the techniques every developer should know:
1. Block Bindings API
The Block Bindings API (stabilized in WordPress 6.5) allows you to dynamically bind block attributes to external data sources like custom fields, site options, or any registered data source. This bridges the gap between static block content and dynamic data. Combined with AI-powered WordPress development tools, these dynamic capabilities open up entirely new workflows:
// Register a custom binding source in functions.php
register_block_bindings_source(
'my-theme/post-meta',
array(
'label' => 'Post Meta',
'get_value_callback' => function( $source_args, $block_instance ) {
$meta_key = $source_args['key'] ?? '';
$post_id = $block_instance->context['postId'] ?? get_the_ID();
return get_post_meta( $post_id, $meta_key, true );
},
'uses_context' => array( 'postId' ),
)
);
// Usage in block markup:
// <!-- wp:paragraph {
// "metadata": {
// "bindings": {
// "content": {
// "source": "my-theme/post-meta",
// "args": { "key": "custom_subtitle" }
// }
// }
// }
// } -->“Block themes are not just a new way to build themes — they represent a fundamental shift in how we think about WordPress development. The template hierarchy, the loop, the hooks — they all still exist, but they are now accessible to everyone through the editor, not just developers writing PHP.”
— Rich Tabor, WordPress Core Contributor and Developer Advocate at Automattic
2. Block Style Variations via theme.json
You can register custom block style variations directly in theme.json without any PHP. This is cleaner than the traditional register_block_style() approach:
// In theme.json, under styles.blocks:
{
"styles": {
"blocks": {
"core/button": {
"variations": {
"gradient-cta": {
"color": {
"background": "linear-gradient(135deg, #1e40af, #7c3aed)",
"text": "#ffffff"
},
"border": {
"radius": "50px"
},
"typography": {
"fontWeight": "700",
"textTransform": "uppercase",
"letterSpacing": "0.05em"
}
}
}
}
}
}
}3. Synced Patterns (formerly Reusable Blocks)
Synced Patterns (renamed from Reusable Blocks in WordPress 6.3) allow you to create a block arrangement that stays synchronized across every instance. When you edit the source pattern, every page and template using it updates automatically. This is ideal for elements like newsletter signup forms, promotional banners, or standardized call-to-action sections.
The key difference from regular patterns: synced patterns maintain a single source of truth. Regular patterns are copied when inserted — changes to the original do not propagate. Synced patterns behave like symbolic links — all instances reflect the current state of the source.
4. Custom Template Hierarchy with FSE
The template hierarchy in FSE mirrors classic WordPress exactly, but with .html files. You can create specific templates for individual posts, pages, categories, or custom post types:
templates/single-product.html— Template for a “product” custom post typetemplates/taxonomy-genre.html— Template for a “genre” custom taxonomy archivetemplates/page-about.html— Template specifically for the “about” pagetemplates/category-tutorials.html— Template for the “tutorials” category archivetemplates/author.html— Template for author archive pages
Migrating an existing classic theme to a block theme is a significant undertaking, but the process is well-documented. Here is a practical roadmap for a smooth migration:
Step 1: Audit Your Current Theme
Before starting, document every template file, widget area, customizer setting, and custom functionality in your current theme. Create a spreadsheet mapping PHP templates to their FSE equivalents.
Step 2: Start with theme.json
Create a theme.json file that mirrors your current theme’s design tokens — colors, fonts, spacing, and layout widths. This ensures visual consistency during the transition. You can add theme.json to a classic theme to gradually adopt FSE features.
Step 3: Convert Templates One at a Time
WordPress supports “hybrid” themes that mix PHP and HTML templates. Start by converting simple templates (like 404.html or search.html), then progressively convert more complex templates. The classic theme continues to function for any template not yet converted to HTML block format.
Step 4: Replace Widget Areas with Template Parts
Each widget area in your classic theme becomes a template part in FSE. The sidebar template part replaces dynamic_sidebar() calls, and widgets are replaced with their block equivalents (e.g., the Search widget becomes the Search block).
Step 5: Migrate Custom Functionality
Custom PHP functions, shortcodes, and template tags need to be evaluated. Some can be replaced with block patterns and custom blocks. Others may need to remain as PHP plugins or custom blocks built with the Block API.
“We are building the infrastructure for the next generation of WordPress themes. The block system means that theme developers can focus on design and user experience rather than reinventing templating logic. That is the real power of Full Site Editing — it raises the floor for what every theme can do.”
— Matias Ventura, Lead Architect of the Gutenberg project
Best FSE Themes for 2026
The block theme ecosystem has grown considerably. Here are the top themes that showcase what FSE can do:
- Twenty Twenty-Five — WordPress’s default theme, showcasing the latest FSE features with clean, minimal design and extensive style variations
- Flavor — A feature-rich theme with 20+ style variations and professional patterns for business sites
- Developer Developer Developer (DDD) — Built specifically for developer portfolios with syntax-highlighted code blocks and dark mode
- Flavor Developer — A lightweight starter theme with excellent documentation for theme developers building custom block themes
- Ollie — A modern starter theme with 50+ patterns, full-page designs, and excellent onboarding for FSE newcomers
- Flavor Developer — A developer-focused theme with comprehensive pattern library and clean code structure
When choosing a block theme, evaluate the pattern library, the number of style variations, theme.json completeness, and how well the theme follows WordPress coding standards. A well-built block theme should provide a solid foundation that users can customize entirely through the Site Editor without touching code.
Block themes have inherent performance advantages over classic themes, but there are best practices to maximize those benefits:
- Use theme.json for styling — Styles defined in theme.json generate optimized CSS custom properties. Avoid adding large custom CSS files when theme.json can handle it.
- Self-host fonts — Use the
fontFacedeclaration in theme.json to bundle fonts locally instead of loading from Google Fonts CDN. This improves GDPR compliance and eliminates external DNS lookups. - Optimize block patterns — Avoid overly complex nested patterns with deep block hierarchies. Flatten structures where possible to reduce DOM depth.
- Leverage the Asset Loading API — WordPress 6.5+ only loads block CSS/JS for blocks actually used on a page. Ensure your theme does not manually enqueue styles that WordPress already handles.
- Use
wp_enqueue_block_style()— For custom block styles, use this function to conditionally load CSS only when the block is present on the page. - Image optimization in patterns — When patterns include images, use responsive image markup with
srcsetandsizesattributes for efficient loading across viewport sizes.
Troubleshooting Common FSE Issues
Working with FSE, you will inevitably encounter some common challenges. Here are solutions to the most frequent issues:
- Templates not appearing — Verify your HTML templates are in the
templates/directory (nottemplate-parts/) and follow the correct naming convention. Check for syntax errors in the block markup. - Global Styles changes not saving — Clear your browser cache and any server-side cache. Global Styles are stored in a custom post type (
wp_global_styles), so database caching plugins can interfere. - theme.json settings not taking effect — Validate your JSON syntax using the WordPress
$schemaURL. A single missing comma or bracket breaks the entire file silently. - Navigation block losing menu items — The Navigation block uses a
wp_navigationpost type. If navigation items disappear, check if the associated navigation entity was accidentally deleted. - Patterns not registering — Ensure patterns use the correct PHP header format. The file must be in the
patterns/directory and have a.phpextension. Verify theSlugheader is unique. - Fonts not loading — Check that font file paths in theme.json use the
file:./prefix relative to your theme root. Verify the font files actually exist at those paths.
WordPress 7.0 is set to bring significant enhancements to the FSE experience. For a comprehensive overview of everything in the upcoming release, read our complete guide to WordPress 7.0. Based on the current development roadmap and Gutenberg Phase 3 (Collaboration) progress, here is what to expect for FSE specifically:
- Real-time collaborative editing — Multiple users editing the same template simultaneously, similar to Google Docs
- Enhanced design tools — More granular control over animations, transitions, and interactive states in the editor
- Improved Block Bindings — More built-in binding sources and a visual UI for creating bindings without code
- Section-level styling — Apply different Global Styles to different sections of a page, enabling varied visual zones within a single template
- Data views for templates — A new management interface for browsing, searching, and organizing templates and patterns at scale
The overarching direction is clear: WordPress is moving toward a future where the visual editor is the primary development tool, with code remaining available as a power-user escape hatch rather than a requirement.
Frequently Asked Questions
Do I need to know PHP to build a block theme?
No. A basic block theme can be built entirely with HTML block markup, JSON (theme.json), and CSS. However, PHP knowledge is valuable for creating block patterns, registering custom block bindings, and adding advanced functionality through functions.php. For complex themes, you will also want familiarity with JavaScript and the WordPress Block API to create custom blocks.
Can I use Full Site Editing with a classic theme?
Partially. You can add a theme.json file to a classic theme to adopt settings and styles features. However, the full Site Editor (template and template part editing) requires a block theme. The recommended approach is a hybrid migration where you gradually convert templates from PHP to HTML block markup.
Is FSE ready for production sites in 2026?
Absolutely. FSE has been stable since WordPress 6.2 and has seen multiple refinement releases since then. Major organizations and agencies are building production sites with block themes. The default WordPress theme (Twenty Twenty-Five) is itself a block theme, demonstrating WordPress’s commitment to FSE as the standard.
How does FSE affect my existing plugins?
Most plugins work seamlessly with block themes. Plugins that rely on widget areas, sidebars, or the Customizer may need updates. Plugins that register Gutenberg blocks continue to work perfectly. The WordPress plugin ecosystem has largely adapted to FSE by 2026.
What is the difference between patterns and template parts?
Template parts are structural components (header, footer, sidebar) that define areas of your site layout and can be swapped per-template. Patterns are pre-designed block arrangements that users insert into content or templates as a starting point. Template parts are referenced by slug and stay synchronized. Patterns (unless synced) are copied when inserted and can be customized independently.
WordPress Full Site Editing represents the most significant evolution in WordPress theme development since the platform’s inception. Whether you are a seasoned developer transitioning from classic themes or a newcomer building your first WordPress site, FSE provides the tools to create professional, performant, and fully customizable websites without the traditional PHP-heavy workflow.
The key takeaways from this guide are: start with a solid theme.json configuration that defines your design tokens; build modular templates using template parts for reusability; leverage block patterns to create consistent, professional designs; and embrace the hybrid migration approach if you are transitioning an existing site.
Ready to take the next step? Start by creating a minimal block theme with just three files (style.css, theme.json, and templates/index.html), then progressively add templates, template parts, and patterns as your understanding deepens. The best way to learn FSE is to build with it.
Block Editor Full Site Editing Gutenberg theme.json WordPress themes
Last modified: February 8, 2026
