Block themes vs classic themes in WordPress

For over a decade (2010 to 2020), WordPress theme development looked the same: you created header.php, footer.php, a loop in index.php, and styles in style.css. Logic lived in PHP, appearance in CSS, and the two worlds rarely met.

With WordPress 5.9 came the Full Site Editing (FSE) approach, now simply called the Site Editor, and in 2026 the question is sharper than ever: should you still write themes in PHP, or move fully to blocks, HTML templates, and theme.json?

This guide breaks down what block themes actually are, how they differ from classic themes at the code level, when each one wins, and how to plan a migration between them. It covers the Classic, Block, and Hybrid models.

Short answer: choose a block theme when you want editor-driven site management, better Core Web Vitals, and a cleaner long-term WordPress roadmap. Keep a classic theme when the project still depends on custom PHP templates, strict layout control, or a page-builder-heavy workflow. The hybrid model sits between the two and is where a large share of professional projects actually land.

#What is a block theme in WordPress?

A block theme is a WordPress theme built entirely from blocks: its templates are HTML files containing block markup instead of PHP files, its design tokens live in a single theme.json file, and every part of the site (header, footer, archives, 404) is editable visually in the Site Editor. Full Site Editing (FSE) is the umbrella term for this system, and it helps to define its pieces before comparing, because several distinct subsystems were introduced together.

The Site Editor (Appearance -> Editor) is a visual interface for editing every part of a site: templates, template parts, styles, patterns, and navigation. In a classic theme you only ever edited post and page content in the block editor. In a block theme, the same block canvas now edits the header, footer, single post template, archive, 404, and search results.

theme.json is a single configuration file at the theme root that declares design tokens and editor settings. It defines the color palette, typography scale, spacing scale, layout widths, and which controls appear in the editor. WordPress reads it and generates CSS custom properties for both the front end and the editor, so the editing view matches the published page.

Block templates and template parts are HTML files under templates/ and parts/. Instead of single.php you ship templates/single.html, and instead of a hard-coded footer in footer.php you ship parts/footer.html. These files contain block markup (HTML comments such as <!-- wp:post-title /-->), not PHP.

Global Styles is the user-facing layer on top of theme.json. Site owners can adjust colors, fonts, and spacing from the Styles panel without touching code, and themes can ship alternative style variations as extra JSON files in a styles/ folder.

Block patterns are reusable, pre-designed block arrangements. They replaced much of what page builders offered: a hero, a pricing section, a call to action, all editable as native blocks and registered from a patterns/ directory.

Understanding these five pieces is most of the battle. A block theme is essentially theme.json plus HTML templates plus patterns, edited through the Site Editor.

#1. Anatomy: PHP vs HTML

This is the most fundamental difference, and the one that unsettles many long-time developers.

#Classic theme

Based on PHP files. When WordPress loads a page, it walks the template hierarchy (for example single-product.php, then single.php, then index.php) and the PHP engine assembles the header, loop, and footer at request time.

• Structure: header.php, page.php, single.php, archive.php, sidebar.php, functions.php.
• Logic: you can freely mix PHP with HTML, for example if ( is_user_logged_in() ) or a fully custom WP_Query loop.
• Strength: full control over markup and easy injection of business logic, third-party API calls, or conditional views.
• Weakness: the site owner cannot touch the header, footer, or layout without editing code or asking a developer.

#Block theme

Based on HTML template files with block markup. There is no PHP in the template files themselves.

• Structure: templates/index.html, templates/single.html, parts/header.html, parts/footer.html, theme.json.
• Logic: none in the template file. Templates are static block markup, and all dynamic output comes from blocks such as <!-- wp:post-title /-->, the Query Loop block, or the Post Content block.
• Strength: the site owner can edit the entire site, including header and footer, in one visual canvas.
• Weakness: custom server-side logic has to move into a custom block, a block variation, the Block Bindings API, or a shortcode, rather than sitting inline in a template.

The mental shift is that presentation logic leaves the template file. Where a classic theme puts a conditional directly in single.php, a block theme expresses the same intent through block context, block bindings, or a purpose-built block registered in a plugin or the theme’s functions.php.

#2. The heart of the theme: functions.php vs theme.json

In the classic era, functions.php was the catch-all: registering menus, sidebars, image sizes, enqueueing stylesheets and scripts, and defining add_theme_support() flags. Design decisions were scattered across PHP and one or more CSS files.

In the block era, theme.json centralizes configuration. It controls:

1. Color palette: the named colors offered to editors, emitted as CSS variables.
2. Typography: font sizes, font families, line height, and fluid type settings.
3. Spacing: a spacing scale and block gap used consistently across blocks.
4. Layout: content width and wide width (contentSize, wideSize) that drive alignment.
5. Controls and availability: appearanceTools, per-block settings, and the ability to disable controls you do not want editors to touch.

Example theme.json in 2026:

{
  "version": 3,
  "settings": {
    "appearanceTools": true,
    "layout": { "contentSize": "720px", "wideSize": "1200px" },
    "color": {
      "palette": [
        { "slug": "primary", "color": "#0055FF", "name": "Brand Blue" }
      ]
    },
    "typography": {
      "fluid": true,
      "fontSizes": [
        { "slug": "small", "size": "14px", "name": "Small" }
      ]
    }
  }
}

Instead of maintaining hundreds of lines of CSS plus PHP registration, you declare tokens once in JSON. WordPress generates optimized CSS and CSS custom properties for the front end and the editor, which is why the editor preview finally matches the published result. functions.php still exists in a block theme, but it becomes small: enqueue a font, register a pattern category, add editor support flags, and little else.

#3. Global Styles and the Site Editor

theme.json sets the defaults; Global Styles lets the site owner override them without code. From the Styles panel, an editor can change the body font, tweak the palette, or adjust spacing, and those choices are stored per site.

Themes can also ship style variations: additional JSON files in a styles/ folder that present the whole site in a different look, for example a dark variation or a high-contrast variation, selectable in one click. This is a capability classic themes never had natively, and it is one of the strongest arguments for block themes on brand-flexible projects.

The tradeoff is governance. Handing an untrained editor full Global Styles access can produce inconsistent typography or broken contrast. Block themes answer this with block locking and by disabling specific controls in theme.json, but the developer has to set those guardrails deliberately.

#4. What about widgets and menus?

In block themes, there is no Widgets screen and no classic Menus screen under Appearance.

• Instead of widgets, you have template parts. The footer is an HTML template part you edit on the same block canvas as any post.
• Instead of the classic menu editor, you have the Navigation block, edited directly in the header, with its menu stored as a reusable wp_navigation entity.

For clients used to older WordPress, this is a genuine culture shock. The familiar “widgets” and “menus” items are gone, replaced by blocks. Some plugins that relied on registering widgets now ship blocks instead, and a few older ones expose their widget only through the legacy Widget block as a compatibility bridge. Auditing plugin compatibility is therefore a real step before committing a client to a block theme.

#5. Feature and capability comparison

The table below summarizes where the two models diverge in day-to-day work.

Read the table as a decision aid rather than a scoreboard. Neither column is universally better; the right choice depends on who edits the site and how much custom server-side logic the templates carry.

#6. Performance and developer experience

On raw front-end performance, block themes generally have the edge.

1. Style loading: WordPress enqueues CSS only for blocks that render on a given page, while a classic theme usually loads one large style.css on every request.
2. Design tokens over stylesheets: theme.json emits CSS custom properties instead of a heavy cascade, which keeps the critical CSS smaller.
3. Cleaner markup, with a caveat: FSE output is often tidy, but nested layout blocks can produce extra wrapper div elements (“div-itis”) if patterns are built carelessly.
4. Core Web Vitals: default block themes such as Twenty Twenty-Six score very well in Lighthouse close to out of the box, because they ship minimal CSS and no jQuery dependency.

Developer experience is more mixed and depends on the team. Block theme development leans on JSON configuration, block markup, and JavaScript for custom blocks (block.json, register_block_type, the @wordpress/scripts toolchain). Teams with deep PHP roots but little React or block tooling experience face a real learning curve. Classic development, by contrast, is immediately familiar to any PHP developer but offers no visual editing to the client and no design-token system without extra work. In practice, the fastest route for a PHP-heavy team is the hybrid theme, which lets them adopt theme.json and patterns first and add custom blocks gradually.

#7. Migrating from a classic theme to a block theme

Migration is rarely a single switch. The content in your database (posts, pages, media) is unaffected, but the presentation layer has to be rebuilt.

Practical considerations:

• Templates: each PHP template needs an equivalent block template. Complex conditional templates may need to be split into patterns plus block bindings.
• Menus: existing menus are not automatically converted; you rebuild them as Navigation blocks, though the menu items can usually be recreated quickly.
• Widgets: widget areas do not exist in a block theme, so sidebar and footer widgets become template parts or blocks.
• Customizer settings: options set through the Customizer (logo, colors, custom CSS) move to theme.json and Global Styles. Custom CSS can be preserved in Global Styles’ additional CSS field during transition.
• Plugin output: verify that every active plugin ships blocks or shortcodes rather than relying on widgets or template hooks that a block theme no longer fires the same way.

A safe path is incremental: first convert the classic theme into a hybrid theme by adding theme.json and block pattern support, verify the design tokens and editor experience, then replace PHP templates with block templates one at a time. This avoids a risky big-bang rewrite and lets you test each template against real content and Core Web Vitals before moving on.

#8. When to stay on a classic theme

A classic theme is still the right call when:

• The project carries heavy custom PHP view logic, such as advanced display conditions, custom loops, or deep WooCommerce template overrides.
• The client is not comfortable with full editing and you need to prevent accidental layout changes to the header or footer.
• The build depends on a page builder such as Elementor or Divi, which still assume a classic structure and largely bypass FSE.
• You maintain a mature site where the migration cost clearly exceeds the benefit.
• The team’s expertise is PHP-first with limited capacity to invest in block tooling right now.

#9. When block themes win

A block theme is the stronger choice when:

• The site is content-led: a corporate site, blog, publication, or portfolio.
• The owner wants to edit headers, footers, and templates without a developer on every change.
• Performance and Core Web Vitals are a priority and you want per-block CSS and design tokens by default.
• Brand flexibility matters and style variations add real value.
• You want to align with the direction of WordPress core, which now concentrates its development on the block and FSE experience.

#10. Recommendation by site type

• Small business or corporate site: block theme. Editors gain safe control over the whole layout, and performance is strong by default.
• Blog or publication: block theme. The Query Loop block, patterns, and clean markup fit editorial workflows well.
• Portfolio or brochure site: block theme, often with a couple of style variations for seasonal looks.
• WooCommerce store: it depends. Modern block-based cart and checkout suit a block theme, but stores with extensive custom PHP product templates may stay classic or hybrid.
• Membership, LMS, or complex application: classic or hybrid. Heavy view logic and third-party integrations are simpler to control in PHP templates.
• Page-builder-driven site: classic. The builder already owns layout, so FSE adds little.

#The hybrid approach

The hybrid model is the pragmatic middle ground. It is a classic PHP theme that adds theme.json (for the color palette, typography, and spacing tokens in the editor) and block pattern support, while keeping selected PHP templates such as header.php or single.php for structural control. Many professional projects in 2026 ship exactly this way, adopting block editing where it helps and keeping PHP where it matters.

#WordPress block theme vs classic theme: which to choose in 2026

The decision depends on three factors: project complexity, client technical skills, and long-term maintenance requirements.

Choose a block theme when:

• The client needs to edit headers, footers, and templates without developer help
• Performance is a priority (block themes load only the CSS for blocks actually used)
• You want to use theme.json for design tokens (colors, typography, spacing) instead of scattered CSS
• The project is a new build with no legacy code to support

Choose a classic theme when:

• You need complex PHP logic in templates (custom loops, conditional layouts, WooCommerce overrides)
• The project relies on widgets, classic menus, or the Customizer
• Your team has deep PHP expertise but limited Gutenberg block development experience
• You are maintaining an existing site and migration cost exceeds benefit

The hybrid approach: Many professional WordPress projects in 2026 use a classic theme with selective block support. Register block patterns and templates where they add value, keep PHP templates where they provide more control. WordPress does not force an all-or-nothing choice.

For WordPress 7.0, block themes will gain additional AI-powered features through the Abilities API, making the FSE path increasingly attractive for new projects.

#Summary

Learn more about WordPress development services at WPPoland. The WordPress world has split into two camps. Don’t fight it. Learn the syntax of theme.json, it’s a skill as important in 2026 as knowing CSS was in 2015. Every professional WordPress developer now needs to be comfortable with both block and classic theme architectures.