Block Themes vs Classic Themes: 2026 Migration Guide

WordPress block themes represent the biggest shift in theme development since custom post types arrived in WordPress 3.0. If you are still running a classic theme in 2026, you are missing out on full site editing, global styles, and significant performance improvements. This complete migration guide walks you through every step of moving from a classic theme to a block theme, covering the key differences, the exact migration path, and the honest trade-offs you should expect.

Why Block Themes Matter in 2026

Block themes are no longer experimental. As of WordPress 6.7, over 60% of new themes on the WordPress.org directory are block themes. The Site Editor has matured considerably, and theme.json v3 gives developers precise control over every design token. Classic themes still work, but they are now in maintenance mode from a core development perspective. New features like style variations, synced patterns, and the block bindings API are built exclusively for block themes. If you want to see which Gutenberg WordPress themes are leading the way, check out our curated list.

For agencies and freelancers building client sites, the migration question is no longer “should we switch?” but “how do we switch without breaking anything?” This guide answers that question with a structured, tested approach.

Block Themes vs Classic Themes: The Key Differences

Before migrating, you need to understand exactly what changes. The shift from classic to block themes affects templates, styling, widgets, navigation, and how you structure your theme files. Here is a detailed comparison.

Template System

Classic themes use the PHP template hierarchy: header.php, footer.php, single.php, archive.php, and so on. Each template file contains a mix of PHP logic, HTML markup, and template tags like the_title() and the_content(). Block themes replace this entire system with HTML template files that contain block markup. A block theme’s templates/single.html file contains blocks like wp:post-title, wp:post-content, and wp:template-part references.

Aspect	Classic Theme	Block Theme
Template files	PHP files (single.php, page.php)	HTML files (single.html, page.html)
Template language	PHP + template tags	Block markup (HTML comments)
Header/Footer	header.php / footer.php	Template parts (parts/header.html)
Template editing	Code editor or child theme	Site Editor (visual, no code needed)
Dynamic data	PHP functions (the_title, etc.)	Block bindings + query blocks
Customization	Customizer + PHP hooks	Site Editor + theme.json

Styling: functions.php vs theme.json

In classic themes, styling involves enqueuing stylesheets via functions.php, writing CSS in style.css, and sometimes using the Customizer API for user-configurable options. Block themes centralize design decisions in theme.json, a structured JSON file that defines color palettes, typography scales, spacing presets, layout widths, and per-block style defaults.

With theme.json v3 (introduced in WordPress 6.6 and refined through 6.8), you get access to shadow presets, aspect ratio controls, background image settings, and granular block-level style overrides. The file effectively replaces hundreds of lines of CSS and PHP Customizer code with a single, declarative configuration.

{
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "color": "#1e40af", "name": "Primary" },
        { "slug": "secondary", "color": "#9333ea", "name": "Secondary" }
      ]
    },
    "typography": {
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "medium", "size": "1rem", "name": "Medium" },
        { "slug": "large", "size": "1.25rem", "name": "Large" }
      ],
      "fontFamilies": [
        {
          "slug": "inter",
          "name": "Inter",
          "fontFamily": "Inter, sans-serif",
          "fontFace": [
            { "fontFamily": "Inter", "fontWeight": "400", "src": ["file:./assets/fonts/inter-regular.woff2"] }
          ]
        }
      ]
    },
    "spacing": {
      "units": ["px", "rem", "%", "vw"]
    }
  },
  "styles": {
    "color": { "background": "#ffffff", "text": "#1a1a1a" },
    "typography": { "fontFamily": "var(--wp--preset--font-family--inter)", "fontSize": "var(--wp--preset--font-size--medium)" }
  }
}

Widgets vs Block-Based Widget Areas

Classic themes rely on widget areas registered with register_sidebar() and populated through the Appearance > Widgets screen. Block themes eliminate the traditional widget system entirely. Sidebars and footer areas become template parts that you edit directly in the Site Editor using any block. This is a significant improvement in flexibility, but it means existing widget configurations do not carry over automatically during migration.

Navigation Menus

Classic themes use wp_nav_menu() and the Appearance > Menus screen. Block themes use the Navigation block, which stores menu items as block markup. The Navigation block supports mega menus, responsive toggles, and per-item styling that classic menus cannot match. During migration, you can import classic menus into Navigation blocks, but the process requires careful testing.

Performance Comparison: Block Themes Are Leaner

Block themes deliver measurable performance improvements over classic themes. Here is why: block themes generate fewer HTTP requests because they do not load jQuery by default, they use native CSS custom properties instead of inline styles, and they serve only the block styles actually used on each page through WordPress’s automatic style loading system.

No jQuery dependency: Classic themes often load jQuery for sliders, accordions, and Customizer previews. Block themes use vanilla JavaScript or no JS at all for layout.
Scoped block styles: WordPress 6.5+ only loads CSS for blocks present on the page. A page with 5 block types loads only those 5 stylesheets, not the entire theme CSS bundle.
CSS custom properties: theme.json values compile to CSS variables, reducing specificity conflicts and enabling efficient style inheritance.
Fewer database queries: Block themes store template content as block markup in the database, eliminating the overhead of widget option lookups and Customizer mod queries.

According to the WordPress Performance Team’s benchmarks, a minimal block theme scores 15-25% higher on Core Web Vitals (LCP and CLS) compared to a classic theme of equivalent complexity. The difference is most pronounced on mobile devices where reduced JavaScript payloads have the biggest impact.

Step-by-Step Migration: Classic Theme to Block Theme

Migrating a live site requires a methodical approach. Rushing this process will break layouts, lose widget configurations, and frustrate content editors. Follow these steps in order.

Step 1: Audit Your Current Theme

Before touching any code, document everything your classic theme does. Create a spreadsheet or checklist that covers:

All template files in use (which PHP templates have custom modifications)
Custom functions in functions.php (shortcodes, custom post types, filters)
Widget areas and their current contents
Navigation menu locations and structures
Customizer settings (colors, fonts, layout options)
Third-party plugin dependencies (page builders, custom CSS plugins)
Custom CSS added via Customizer or plugins

“The most common migration failure is not technical — it is forgetting to document what the classic theme was actually doing. Theme functions that have been running silently for years suddenly disappear when you switch themes.”
Developer.WordPress.org Block Theme Documentation

Step 2: Set Up a Staging Environment

Never migrate on a production site. Create a staging copy using your host’s staging tools, a local development environment (like Local by Flywheel), or a plugin like WP Staging. You need an exact replica of your live site to test the migration safely. Verify that all plugins, content, and settings are identical on staging before proceeding.

Step 3: Choose or Build Your Block Theme

You have three options for the target block theme:

Use an existing block theme: Themes like Twenty Twenty-Five, Flavor, Flavflavor, Ollie, or Developer Blog provide solid starting points. Browse the block themes directory for options matching your design needs.
Convert your classic theme: If your classic theme has strong brand identity, you can build a block theme that replicates it. Use the Create Block Theme plugin to scaffold the structure.
Build a custom block theme from scratch: For maximum control, start with a blank block theme and build every template and pattern. This is the best approach for agencies building client sites.

Step 4: Migrate theme.json Settings

Translate your classic theme’s Customizer settings and CSS variables into theme.json. Map colors to the palette, fonts to fontFamilies with local font faces, and spacing values to spacingSizes. If your classic theme used the Customizer for a dozen color options, those all become palette entries in theme.json. Every add_theme_support() call in your classic theme likely has a theme.json equivalent.

Classic Theme (functions.php)	Block Theme (theme.json)
add_theme_support(‘editor-color-palette’, […])	settings.color.palette
add_theme_support(‘editor-font-sizes’, […])	settings.typography.fontSizes
add_theme_support(‘custom-spacing’)	settings.spacing.units
add_theme_support(‘align-wide’)	settings.layout.contentSize / wideSize
Custom CSS variables in style.css	styles.css / Custom CSS in theme.json
wp_enqueue_style for Google Fonts	settings.typography.fontFamilies with fontFace

Step 5: Convert Templates to Block Markup

This is the most labor-intensive step. Each PHP template file must be recreated as an HTML block template. For a typical theme, the conversion looks like this:

header.php becomes parts/header.html containing site-title, site-tagline, navigation, and any header blocks
footer.php becomes parts/footer.html with columns of paragraph blocks, social links, and copyright text
single.php becomes templates/single.html with wp:template-part (header), wp:post-title, wp:post-featured-image, wp:post-content, wp:post-terms, wp:comments, wp:template-part (footer)
archive.php becomes templates/archive.html using the Query Loop block to display post lists
sidebar.php is eliminated entirely — sidebar content moves into template parts or block patterns

The Create Block Theme plugin can export your current site’s appearance as block theme files, giving you a starting point. From there, refine the templates in the Site Editor. Understanding how WordPress organizes theme files within the wp-content directory structure will help you navigate the template file locations during conversion.

Step 6: Recreate Widget Areas as Template Parts

For each widget area in your classic theme, create a corresponding template part. A footer with three widget columns becomes a footer template part with a Columns block containing the same content as blocks. A sidebar with recent posts, categories, and a search box becomes a sidebar template part with those specific blocks arranged vertically.

There is no automatic widget-to-block migration tool that handles all cases reliably. Plan to manually recreate each widget area. Take screenshots of your current widget layouts for reference.

Step 7: Migrate Navigation Menus

WordPress provides a built-in classic menu importer within the Navigation block. In the Site Editor, add a Navigation block, click the three-dot menu, and select “Import from Classic Menus.” This pulls your existing menu structure into block format. After importing, verify that all links work, submenu dropdowns render correctly, and any custom CSS classes on menu items are preserved or replaced with block styling.

Step 8: Move Custom PHP to a Plugin

Any custom functionality in your classic theme’s functions.php that is not theme-specific should move to a site-specific plugin. This includes custom post types, taxonomies, shortcodes, REST API endpoints, and admin customizations. Block themes can still have a functions.php file, but best practice is to keep it minimal, using it only for theme-specific features like pattern registration and block style variations.

Step 9: Create Block Patterns

Block patterns are reusable block layouts that replace what classic themes accomplished with page templates and shortcodes. If your classic theme had a “Team Page” template, create a “Team Grid” pattern. If it had a “Pricing Table” shortcode, build a “Pricing Comparison” pattern using columns, headings, and list blocks. Register patterns in your theme or use the Site Editor’s pattern management.

// Register a block pattern in functions.php
register_block_pattern(
    'mytheme/pricing-table',
    array(
        'title'       => 'Pricing Table',
        'description' => 'A three-column pricing comparison',
        'categories'  => array( 'featured' ),
        'content'     => ' ... ',
    )
);

Step 10: Test Thoroughly and Go Live

On your staging site, test every page template, post type, archive, search results page, and 404 page. Check responsive behavior on mobile and tablet. Verify that all plugins render correctly within the block theme’s templates. Run a full-site crawl to catch broken links or missing styles. Only after thorough testing should you schedule the production switchover.

theme.json v3: What Changed and Why It Matters

Theme.json v3, stabilized in WordPress 6.8, brings several important changes over v2:

Default font sizes renamed: The default font size slugs changed to avoid conflicts with theme presets. If you were using v2, review your fontSizes slugs for compatibility.
Shadow presets: You can now define box-shadow presets in theme.json and apply them to any block via the Site Editor, eliminating the need for custom CSS.
Background image support: Groups and Covers can receive background images defined in theme.json styles, not just through the block editor UI.
Aspect ratio controls: Image blocks and other media blocks respect aspect ratio settings defined globally or per-block in theme.json.
Block-level style overrides: You can target specific blocks with custom styles in the styles.blocks section, giving you the precision that previously required custom CSS files.

Refer to the official WordPress theme.json documentation for the complete schema reference and migration notes from v2 to v3.

Block Patterns Replacing Widgets and Page Templates

Block patterns are the single most powerful replacement for classic theme features. They serve three roles that previously required separate systems:

Widget replacements: Instead of registering widget areas and hoping users install the right widgets, ship patterns that editors can insert into template parts. A “Newsletter Signup” pattern is more flexible than a newsletter widget because it can include images, custom styling, and layout variations.
Page template replacements: Classic themes often shipped 5-10 page templates (full-width, sidebar-left, landing page, etc.). Block patterns combined with template modifications in the Site Editor replace all of these. Users can apply patterns to any page without being locked into a specific template.
Shortcode replacements: Patterns replace most shortcode use cases. A “Feature Grid” shortcode becomes a “Feature Grid” pattern that editors can visually customize after insertion.

Synced patterns (formerly “reusable blocks”) take this further by allowing one pattern to update everywhere it is used, similar to how global widgets worked in classic themes but with full block editing capabilities.

Honest Limitations: What Is Harder in Block Themes

Block themes are the future, but they are not perfect. Here are the legitimate challenges you should prepare for:

Complex dynamic layouts: If your classic theme uses advanced PHP logic to conditionally display elements (different headers based on user role, dynamic sidebars per category), replicating this in block markup is harder. You may need custom blocks or the block bindings API.
Legacy plugin compatibility: Some older plugins inject content via PHP hooks that assume a classic theme structure. Plugins relying on wp_head, wp_footer, and specific hook positions generally work fine. Plugins that modify the_content or template output may need updates.
Learning curve for developers: Developers experienced with PHP template tags face a learning curve with block markup, the Site Editor, and theme.json. The mental model is fundamentally different — you are composing with blocks, not coding with functions.
Limited server-side rendering: Some designs require server-side logic that block themes handle differently. Dynamic blocks solve many cases, but complex server-rendered layouts may need custom block development.
WooCommerce and LMS integration: E-commerce and learning management plugins have been adapting to block themes, but some still render better in classic themes. Check your specific plugins’ block theme compatibility before committing to migration.

Migration Checklist: Before, During, and After

Use this checklist to track your migration progress from start to finish.

Before Migration

Full site backup (files + database)
Staging environment set up and verified
Classic theme audit complete (templates, functions, widgets, menus)
Target block theme selected or scaffolded
Plugin compatibility checked for all active plugins

During Migration

theme.json created with all design tokens
All templates converted to block markup
Template parts created for header, footer, sidebar
Navigation menus imported and verified
Widget content recreated as template parts or patterns
Custom PHP moved to site-specific plugin
Block patterns created for reusable layouts

After Migration

Every page and post visually inspected
Mobile and tablet responsiveness verified
Forms, search, and interactive elements tested
Core Web Vitals checked (expect improvement)
Content editors trained on Site Editor workflow
Classic theme deactivated (keep installed for 30 days as rollback)

Best Practices for a Smooth Transition

Start with a fresh block theme on staging rather than trying to hybridize your classic theme. Hybrid approaches create technical debt.
Use the Create Block Theme plugin to export your Site Editor customizations back into theme files. This prevents your customizations from living only in the database.
Version control your theme.json and template files. Block themes are more declarative, making Git diffs more readable than classic PHP templates.
Document your patterns so content editors know which patterns are available and when to use them.
Keep functions.php minimal in your block theme. Move non-theme functionality to plugins. The less PHP in your theme, the easier it is to maintain.
Test with WordPress beta releases to catch block theme compatibility issues before they reach production.

Frequently Asked Questions

Can I use a block theme with WooCommerce?

Yes, but with caveats. WooCommerce 8.0+ includes block-based templates for product pages, cart, and checkout. However, some WooCommerce extensions and customizations still assume classic theme hooks. Test your specific WooCommerce setup on staging before migrating. The core WooCommerce experience works well with block themes, but heavily customized stores may need additional development work.

Will my existing content break when I switch to a block theme?

Your post and page content (the_content) will remain intact because it is stored in the database independently of the theme. What changes is the “chrome” around your content: headers, footers, sidebars, and page templates. Block themes render your content using their own templates, so the surrounding layout will change. The content itself, including any blocks you have already used in the block editor, will display correctly.

Do I need to learn React or JavaScript to work with block themes?

No, not for basic block theme development. Creating and customizing block themes primarily involves HTML block markup, theme.json configuration, and CSS. You only need JavaScript or React if you are building custom blocks. The Site Editor handles most visual customization without any code. For advanced dynamic blocks, basic JavaScript knowledge helps, but it is not a prerequisite for migration.

How long does a typical migration take?

For a standard business site with 5-10 custom templates and a few widget areas, expect 2-4 days of development work plus 1-2 days of testing. For complex sites with custom post types, advanced layouts, and deep plugin integrations, plan for 1-3 weeks. The biggest variable is how much custom PHP logic needs to be reimplemented as blocks or patterns.

Should I wait for WordPress 7.0 to migrate?

No. The block theme system is mature and stable as of WordPress 6.7+. Waiting for the next major release means missing out on performance improvements, better editor experiences, and the growing ecosystem of block-first plugins and patterns. The best time to migrate is now, while you can do it at your own pace rather than being forced into it when classic theme support eventually diminishes.

Conclusion: Make the Move to Block Themes

Block themes are not just a new way to build WordPress themes. They represent a fundamental improvement in how themes handle templates, styles, and user customization. The migration from a classic theme to a block theme requires planning and careful execution, but the result is a faster, more maintainable, and more flexible site.

Start with a staging site, audit your current theme thoroughly, and work through the migration steps methodically. Use theme.json v3 to centralize your design tokens, create patterns for reusable layouts, and move custom PHP to plugins where it belongs. If you are also evaluating page builder alternatives to Elementor, block themes with the native Site Editor may be the best long-term replacement.

The WordPress ecosystem is moving decisively toward block themes. Getting ahead of this transition gives your sites a performance advantage and positions your development workflow for everything coming next in WordPress full site editing.

Ready to start your migration? Explore the official block theme developer documentation and try converting a simple classic theme as a learning exercise. The skills you build will pay dividends across every WordPress project you touch.

Block Themes vs Classic Themes: Complete Migration Guide for 2026