If you’ve been building WordPress sites for any length of time, you’ve noticed the ground shifting beneath your feet. The question of WordPress block theme vs classic theme isn’t just academic anymore, it’s a practical decision that shapes how you structure every project in 2026. Block themes (also called Full Site Editing themes) aren’t a future feature; they’re the present reality. But classic themes aren’t dead either. Knowing when to use each approach, and how to migrate when the time is right, separates the developers who adapt from those who get left behind.
This guide covers everything: how theme.json works, how template parts and block patterns change your workflow, what style variations can do for client projects, and the concrete migration path from a classic PHP theme to a block theme. You’ll also find honest guidance on when classic themes still make sense, because sometimes they genuinely do.
What Defines a Block Theme in 2026
A block theme replaces PHP template files with block-based HTML templates. Instead of header.php, single.php, and footer.php, you work with HTML files that contain Gutenberg block markup. The WordPress site editor, not a PHP function, handles how every part of the page renders.
The defining characteristics of a block theme are:
- theme.json, the single configuration file that replaces dozens of
add_theme_support()calls and scattered CSS variables - Block templates, HTML files in
/templates/that define page structures using Gutenberg block markup - Template parts, reusable block HTML fragments in
/parts/(header, footer, sidebar) - Block patterns, pre-designed content layouts registered and used across templates
- Style variations, alternate theme.json configurations bundled in
/styles/that let users switch color/typography schemes - No
functions.phpfor layout, layout decisions belong in theme.json and templates, not PHP
A classic theme, by contrast, controls rendering through PHP templates, hooks (wp_head, wp_footer, the template hierarchy), and enqueued stylesheets. The block editor is an add-on to classic themes, present but not central.
Understanding theme.json: The Architecture of a Block Theme
theme.json is the most important file to understand if you’re moving from classic to block theme development. It centralizes typography, color palettes, spacing scales, layout constraints, and block-level defaults into one JSON structure. Get comfortable with it and block theme development snaps into focus.
The Core Shape of theme.json
Every theme.json file follows a predictable hierarchy. The settings key controls what options are available in the editor. The styles key controls global CSS applied to the site. The customTemplates and templateParts keys register the templates and parts your theme provides.
See the Gist below for a production-ready theme.json structure covering typography, color palette, spacing, and layout constraints:
Color Palettes and Design Tokens
In a classic theme, you’d define color variables in style.css and reference them in functions.php via add_theme_support('editor-color-palette'...). In a block theme, the same information lives in theme.json under settings.color.palette. WordPress generates CSS custom properties from these automatically, you don’t write the CSS variables by hand.
The generated variable follows the pattern --wp--preset--color--{slug}. If you define a color with slug primary, WordPress outputs --wp--preset--color--primary as a CSS custom property you can reference anywhere in your stylesheets or within theme.json styles.
Typography Scales
Font sizes in theme.json work similarly to colors. You define a scale under settings.typography.fontSizes, and WordPress generates --wp--preset--font-size--{slug} variables. The fluid property allows you to define responsive font sizes using CSS clamp(), WordPress handles the clamp() generation from the min and max values you provide.
theme.json doesn’t just configure the editor, it’s the design token system for your entire theme. Every color, every font size, every spacing value flows from this single source of truth.
Spacing Scales and Layout Constraints
Spacing in theme.json uses settings.spacing.spacingSizes for a named scale, and settings.layout for content width constraints. The contentSize and wideSize values under settings.layout replace the classic theme’s max-width CSS rules and the add_theme_support('align-wide') call.
Template Parts: Replacing the PHP Template Hierarchy
Classic themes use a PHP template hierarchy, single-post.php, archive-category.php, page-contact.php, with shared pieces pulled in via get_header(), get_footer(), and get_template_part(). Block themes replace this entirely with HTML templates and template parts.
How Template Parts Work
Template parts live in the /parts/ directory of your theme. Each is an HTML file containing Gutenberg block markup. You reference them in your templates using the Template Part block. WordPress knows about your parts because you declare them in theme.json under templateParts.
The key difference from classic PHP parts: users can edit template parts directly in the site editor without touching code. A client can rearrange the header, change the footer links, or modify the sidebar, all through the WordPress interface. This is either a benefit or a risk depending on your client relationship. Locking blocks in template parts (using lock attributes) lets you protect structural elements while leaving content-level blocks editable.
The Gist below shows a complete template structure, header, footer, and single post template, with proper template part references:
Template Hierarchy in Block Themes
Block themes support the same template hierarchy logic as classic themes, WordPress looks for the most specific template first, falling back to more general ones. The difference is that templates are HTML files rather than PHP files, and they live in /templates/ rather than the theme root. Custom templates for specific posts or pages can be assigned in the editor without any PHP registration.
| Classic Theme File | Block Theme Equivalent |
|---|---|
header.php | /parts/header.html |
footer.php | /parts/footer.html |
single.php | /templates/single.html |
page.php | /templates/page.html |
archive.php | /templates/archive.html |
index.php | /templates/index.html |
functions.php (theme support) | theme.json (settings) |
style.css (global CSS) | theme.json (styles) + style.css |
Block Patterns: The New Content Building Blocks
Block patterns are pre-designed arrangements of blocks that users can insert into posts and pages. In a block theme, patterns take on a structural role beyond just content helpers, they can define full page sections, hero areas, feature grids, and call-to-action layouts that editors drop in and customize.
Registering Patterns in a Block Theme
Patterns can be registered three ways in a block theme. The traditional PHP method via register_block_pattern() in functions.php still works. The file-based method, introduced in WordPress 6.0, lets you place pattern PHP files in a /patterns/ directory, WordPress picks them up automatically. The third method is the patterns directory at wordpress.org, from which users can install patterns directly.
The file-based pattern registration is the preferred method for block themes because it keeps pattern code colocated with the theme files and avoids cluttering functions.php. Each file starts with a header comment declaring the pattern’s title, slug, categories, and viewport width:
Synced vs Unsynced Patterns
WordPress distinguishes between synced patterns (previously called “reusable blocks”) and unsynced patterns. Synced patterns update everywhere they’re used when you change the source, useful for persistent elements like a newsletter CTA. Unsynced patterns are starting points that users customize independently in each location.
For theme developers, this distinction matters when designing pattern libraries. Structural patterns used as page scaffolding should generally be unsynced. Content blocks that must stay consistent, legal disclaimers, recurring CTAs, brand taglines, should be synced.
Style Variations: Multiple Looks from One Theme
Style variations are alternate theme.json configurations bundled with your theme in a /styles/ directory. Users switch between them in the site editor under Styles. Each variation can override colors, typography, spacing, and block-specific defaults from the main theme.json.
This feature changes the economics of theme development significantly. Instead of building separate child themes or multiple themes for clients with different brand colors, you build one block theme with three or four style variations covering different palettes. The client picks the variation closest to their brand in the editor, then fine-tunes from there.
Building a Style Variation
A style variation file sits at /styles/{variation-name}.json and follows the same schema as theme.json. You only need to include the keys you’re overriding, everything else inherits from the base theme.json. A minimal dark mode variation, for example, might only override the color palette and a few typography colors:
WordPress 6.6 and later support per-block style variations, allowing you to offer multiple design options for specific blocks (like headings or buttons) independently of the global style variation. This granularity opens the door to sophisticated design systems within a single theme.
The Migration Path: Classic Theme to Block Theme
Migrating an existing classic theme to a block theme is a substantial undertaking. It’s not a settings toggle, you’re replacing the rendering architecture. The migration path has three viable approaches depending on your constraints.
Option 1: Hybrid Theme (Incremental Migration)
A hybrid theme uses classic PHP templates alongside the block editor. You retain your existing PHP template hierarchy but adopt Gutenberg blocks for content areas. This is the lowest-risk migration path for existing sites because nothing breaks immediately.
The limitation is that hybrid themes don’t get the full block theme benefits, no site editor, no template editing in the admin, no style variations. They’re a stepping stone, not a destination. Use this approach when you need to continue delivering on an existing classic theme project while gradually moving toward block development.
Option 2: Block-Based Child Theme
If your classic theme is well-maintained and from a vendor who offers a block theme version, a block-based child theme of the new parent is often the fastest path. You get the block theme architecture while keeping customizations isolated in the child. This only works if the parent theme has made the jump to block themes themselves.
Option 3: Full Rebuild as Block Theme
For new projects or major redesigns, build directly as a block theme from scratch. This is the highest-effort option for existing sites but produces the cleanest result. The migration checklist for a full rebuild:
- Audit existing templates, map every PHP template file to its block theme HTML equivalent
- Extract design tokens, pull all CSS variables, color values, font stacks, and spacing values into theme.json
- Convert PHP templates to HTML templates, replace PHP logic with block markup; dynamic data comes from Query Loop blocks and Block Bindings API
- Convert template parts, header.php, footer.php, sidebar.php become parts/*.html files
- Build pattern library, identify recurring content layouts in the old theme and register them as patterns
- Test template hierarchy coverage, ensure you have templates for all post types and archive views the site uses
- Migrate custom widgets, classic widgets don’t work in block themes; replace them with blocks or custom block plugins
- Audit enqueued scripts/styles, block themes still use functions.php for PHP logic; keep only what’s necessary
Handling PHP Logic in a Block Theme
Block themes still have a functions.php file. Custom post type registration, REST API endpoints, block registration, plugin dependencies, security functions, all of that PHP stays in functions.php. What moves out is layout and display logic. The rule is simple: if it controls how something looks or where it appears on the page, it belongs in theme.json or templates. If it controls data, permissions, or custom functionality, it stays in PHP.
The Block Bindings API (stable since WordPress 6.5) lets you bind dynamic data to block attributes without PHP templates. You can display post meta, custom fields, or plugin-provided data sources directly in block templates using the bindings attribute, no PHP template logic required for most display cases.
When Classic Themes Still Make Sense
The industry narrative tends toward “block themes are the future, classic themes are legacy.” That framing misses important nuance. Classic themes remain the right choice in specific situations, and forcing a migration in those situations creates unnecessary complexity without meaningful benefit.
Heavy Custom PHP Rendering Requirements
Sites with complex server-side rendering logic, dynamic pricing tables, member-specific content assembled from multiple data sources, real-time inventory displays, often have rendering logic so deeply embedded in PHP templates that extracting it for a block theme provides little benefit at high cost. The Block Bindings API and dynamic blocks can handle more cases than they used to, but highly customized render pipelines are still easier to maintain as classic PHP templates.
Existing Production Sites With No Redesign Budget
A classic theme running reliably on a production site that generates business value should not be migrated just to be modern. The risks of a template architecture migration, broken layouts, lost customizations, plugin compatibility issues, are real. Migrate when there’s a concrete benefit to deliver, not just because block themes are newer.
Page Builder Sites
Sites built on Elementor, Divi, Beaver Builder, or Bricks don’t benefit meaningfully from block theme adoption. These page builders have their own template systems, their own design token implementations, and their own site editing interfaces. Layering block theme concepts on top of a page builder creates confusion without benefit. If you’re deep in a page builder ecosystem, stay there until you’re ready for a full rebuild.
Legacy Plugin Dependencies
Some plugins, particularly older membership plugins, LMS platforms, and custom field frameworks, register custom templates and override the WordPress template hierarchy in ways that conflict with block theme template parts. Before migrating a site with significant plugin dependencies, audit whether each plugin is block-theme compatible. This is especially important for plugins that register widget areas, as classic widgets don’t work in block themes.
Block Theme vs Classic Theme: Performance Comparison
Performance differences between block and classic themes are real but often overstated. Block themes don’t automatically produce faster sites, and classic themes don’t automatically produce slower ones. The differences come from specific implementation choices.
| Factor | Block Theme | Classic Theme |
|---|---|---|
| CSS delivery | Per-block inline styles (can increase inline CSS) | Single enqueued stylesheet (usually one HTTP request) |
| JavaScript | Block scripts loaded per-block as needed | Often monolithic enqueued scripts |
| HTML output | Can include wrapping div soup from nested blocks | Developer controls HTML directly |
| Interactivity API | Native, optimized client interactions | Requires manual JS integration |
| Template caching | Block templates processed each request | PHP opcode cache covers template files |
| Asset loading | Block-specific assets loaded conditionally | All assets typically loaded globally |
In practice, a well-optimized classic theme and a well-optimized block theme land within a few points of each other on Core Web Vitals. The bigger performance wins come from server configuration, caching, image optimization, and build-time asset optimization, factors independent of theme architecture.
Developer Tooling for Block Theme Development
The toolchain for block theme development has matured considerably. The @wordpress/scripts package handles webpack bundling, SASS compilation, and TypeScript support out of the box. The @wordpress/create-block CLI scaffolds custom blocks. For theme development specifically, wp-env provides a Docker-based local environment that mirrors the WordPress.org test matrix.
Theme JSON Schema Validation
Add the $schema property to your theme.json to get IDE validation and autocompletion in VS Code and other editors that support JSON Schema. The official schema is published at https://schemas.wp.org/trunk/theme.json. This single addition gives you inline documentation, type checking, and autocomplete for every theme.json property without installing extra tooling.
Block Theme Testing Workflow
The WordPress Theme Review team maintains theme-check and the Theme Unit Test data set. Block themes should pass both. Beyond that, test in the site editor specifically, block template editing, style variation switching, pattern insertion, and template part editing should all work without console errors. The Gutenberg plugin (the development branch of the block editor) is worth testing against even if you target core WordPress, as it previews APIs that will land in future releases.
Block Theme Development Best Practices for 2026
- Start with theme.json, define your design tokens first; don’t write raw CSS until you’ve exhausted what theme.json can do
- Use spacing scale values, reference spacing presets rather than hardcoded pixel values for consistent spacing across blocks
- Register patterns liberally, patterns reduce the effort editors need to produce well-designed pages; over-registering is better than under-registering
- Lock structural blocks, use lock attributes on blocks in template parts that should not be moved or deleted by non-developer users
- Leverage Block Bindings API, instead of custom shortcodes for dynamic data, use bindings to keep dynamic content within the block editor paradigm
- Test style variations last, build the base theme.json theme completely before creating variations; variations are harder to maintain if the base keeps changing
- Keep functions.php minimal, resist the pull to add display logic to PHP; every layout decision in PHP is one that editors cannot control in the site editor
- Version your theme.json, the schema version matters; always target the current version for the WordPress release you’re developing against
Real-World Decision Framework
When a new project lands, use this framework to choose your theme architecture:
| Situation | Recommendation |
|---|---|
| New WordPress site, no legacy constraints | Block theme, start fresh with full FSE |
| Redesign of existing classic theme site | Block theme, migration cost justified by redesign budget |
| Existing site, minor updates only | Stay classic, migration risk exceeds benefit |
| Site with heavy page builder usage | Stay in page builder ecosystem, don’t mix paradigms |
| Site with complex PHP render logic | Hybrid or classic, evaluate Block Bindings API first |
| Client needs visual editing of entire site | Block theme, site editor is the strongest argument for migration |
| Plugin-heavy site with legacy dependencies | Audit plugin compatibility before committing to block theme |
Conclusion
The shift from classic themes to block themes isn’t about abandoning what worked, it’s about adopting an architecture built for the way WordPress is evolving. theme.json, template parts, block patterns, and style variations give you tools that make client work faster, design systems more consistent, and editorial workflows genuinely better than what classic themes provided.
That said, classic themes remain valid for specific use cases. The skill is knowing which architecture serves your project, and having enough fluency in both that you can make that call quickly. Block themes are the default choice for new projects in 2026. Classic themes are the right choice when migration cost exceeds benefit or when complex PHP rendering requirements demand it.
Start building block themes now if you haven’t already. The learning curve is front-loaded, theme.json has a lot of properties to internalize, but once you’re through it, you’ll build faster and deliver more flexible sites than classic PHP templating ever allowed.
If you’re working with the Gutenberg editor and want to go deeper on FSE, read our complete guide on WordPress Full Site Editing (FSE). To see how block architecture enables leaner sites, explore how developers are building WordPress sites with only core blocks and no page builders.
Frequently Asked Questions
Can I use a classic theme with the block editor in WordPress 2026?
Yes. Classic themes fully support the Gutenberg block editor for post and page content. What you don’t get with a classic theme is the site editor, the ability to edit headers, footers, templates, and global styles visually. If your site doesn’t need site editor functionality, a classic theme with the block editor works fine.
What is the minimum WordPress version required for block themes?
Block themes are supported from WordPress 5.9 onward (January 2022). However, for the full feature set covered in this guide, including the Block Bindings API and per-block style variations, you need WordPress 6.5 or later. For active development in 2026, target WordPress 6.7+.
Do block themes support custom post types and taxonomies?
Yes, fully. Block themes support any post type registered with show_in_rest: true and template hierarchy templates (e.g., /templates/single-{post-type}.html). Custom taxonomies work through archive templates. Register post types and taxonomies in functions.php as normal, the theme architecture change doesn’t affect registration.
How do I add custom CSS in a block theme?
Three ways. First, use the styles.css property in theme.json to add global CSS inline. Second, enqueue a style.css in functions.php as normal. Third, use the Additional CSS panel in the site editor for per-site customizations. For theme development, put structural CSS in theme.json styles, component-specific CSS in an enqueued stylesheet, and encourage clients to use the site editor Additional CSS panel for minor tweaks.
Will migrating to a block theme break my existing content?
Post and page content is stored independently of the theme and will not be affected by a theme change. The risk area is template-level customizations, custom page templates, widget area content, theme-specific shortcodes, and custom fields displayed via theme functions. Run a staging migration first, audit all template-specific content, and replace shortcodes and widget area content with block equivalents before going live.
Block Editor Block Themes Classic Themes Full Site Editing theme.json
Last modified: April 9, 2026
