Classic theme required files vs block themes in WordPress

Classic theme required files still start the same way they did from 2010 to 2020: 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, design tokens in one file, and alignment with where WordPress core development is going. 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. For what the Gutenberg plugin ships today, including React 19 defaults, see Gutenberg 24.2: margin notes and React 19.

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.

#Classic theme required files: style.css and index.php

A classic theme needs exactly two files before WordPress will list it and let you activate it: style.css, whose header comment carries the theme name and the rest of the metadata, and index.php as the last-resort template. Everything else you normally see, header.php, footer.php, functions.php, single.php, page.php, is optional in the strict sense and becomes necessary only when you want the template hierarchy to branch. A block theme swaps the second file: style.css still holds the header comment, but the fallback template is templates/index.html rather than index.php. theme.json is not formally required either, though a block theme without it inherits core defaults for colours, spacing and typography, which is almost never what you want. A child theme adds one rule on top: the Template: line in its style.css header has to name the parent folder.

#1. Block theme vs classic theme template files

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. What theme.json replaces in functions.php

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. How to structure those tokens as a design system shared across projects is covered in the guide to scalable design systems with Gutenberg. 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. How Global Styles and style variations work

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 happens to widgets and menus in a block theme

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. Block theme vs classic theme feature 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. Are block themes faster than classic themes

For years the answer was a clear yes, and since WordPress 6.9 it is much narrower.

1. Core block styles: block themes load the CSS of core blocks per block and only for blocks that render, because _add_default_theme_supports() turns on should_load_separate_core_block_assets and should_load_block_assets_on_demand. Classic themes used to get the bundled wp-block-library stylesheet on every page. Since 6.9, wp_load_classic_theme_block_styles_on_demand() sets the same two filters for classic themes and adds an output buffer that moves late styles into the head. The buffer has a cost: it stops the response from streaming, so time to first byte can rise slightly. A theme that needs streaming can switch it off through the wp_should_output_buffer_template_for_enhancement filter.
2. Design tokens over stylesheets: theme.json emits CSS custom properties instead of a heavy cascade. A classic theme gets the same tokens once it ships a theme.json file.
3. The theme’s own stylesheet: this is where a real gap remains. A classic theme often carries one large style.css with every component, while a block theme keeps most styling in theme.json and per-block styles.
4. 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.

A theme does not have a Lighthouse score; a page does. On a real site the result depends on the consent banner, embedded maps and forms, font files and image sizes far more than on the theme type. Measure your own pages; the Core Web Vitals guide covers how.

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 to use a block theme

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.
• You want design tokens and per-block styling by default rather than a large theme stylesheet.
• 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. Block or classic theme for WooCommerce, blogs and LMS

• 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.

#What is a hybrid WordPress theme

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.

#Which Site Editor features work with classic themes, by WordPress version

The line between the two theme types has moved with almost every release. The Theme Handbook calls hybrid themes “classic themes that have adopted some modern block-related features” and notes that hybrid is not an official theme type (What is a theme). The table lists what reached classic themes and when, with release dates from the WordPress releases archive.

In current core, wp-admin/menu.php gives a classic theme the full Design entry in the Site Editor when it ships theme.json or declares editor-styles support, and only the Patterns entry otherwise. A block theme gets the Editor entry. So the practical question in 2026 is rarely “classic or block” in the abstract. It is which of these features a project adopts, in which order, and whether the last step, adding templates/index.html, is worth taking at all.

#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
• Editors should change templates and global styles without a deployment
• 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.

WordPress 7.0 shipped on May 20, 2026 and 7.1 on August 19, 2026; the current release is 7.1.3 from October 6, 2026. The Abilities API arrived earlier, in 6.9, and works the same under both theme types, so it is not an argument for either architecture.

#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.