WordPress Block Theme vs Classic Theme: The Honest Comparison

Open your theme folder. If it contains a templates directory with an index.html inside it, plus a theme.json at the root, you have a block theme. If it contains index.php alongside files like header.php and footer.php, and your admin sidebar shows Appearance then Customizer, you have a classic theme.

That single structural difference decides who can change what on your site, where those changes are stored, and which half of the WordPress plugin ecosystem behaves normally.

The 30-second identification

Signal	Classic theme	Block theme
Root template file	index.php	templates/index.html
Header and footer	header.php, footer.php	parts/header.html, parts/footer.html
Global config	functions.php	theme.json (plus optional functions.php)
Admin menu	Appearance > Customizer	Appearance > Editor
Where edits are saved	Files on disk	Database, as wp_template posts
Widgets screen	Present	Absent

WordPress makes the call by looking for templates/index.html. A theme that ships a theme.json but keeps its PHP templates is still treated as classic — that middle state is common and it has a name, covered below.

If you have shell access, one command settles it:

wp eval 'var_dump( wp_is_block_theme() );'

WP-CLI is the fastest check on a site you did not build, especially when a page builder has hidden the usual admin menus.

What changes for the person editing the site

In a classic theme, the header, footer, sidebar, colors, and logo live behind the Customizer, and you only get the controls the theme author decided to build. If the theme did not register a control for the footer copyright text, there is no control. You edit a PHP file or you live with it.

In a block theme, the Site Editor exposes the entire page. Header, footer, the loop, the 404 page, the search results layout — all of it is blocks, all of it is editable by someone who has never seen PHP. That is the real headline feature, and it is genuinely large.

The cost is that everything is editable by someone who has never seen PHP. A client can delete the site title from the header at 2am and there is no version history on disk to restore from — only the Site Editor’s own revisions. Locking things down is possible with block locking and by restricting who reaches the editor, but it is opt-in work you have to remember to do.

Two smaller losses that bite in practice: block themes have no Widgets screen (widget areas are replaced by template parts and blocks), and classic menus are replaced by the Navigation block, which stores its items as a separate content type rather than in the familiar Menus screen.

What changes for the developer

Classic themes use the PHP template hierarchy. WordPress resolves a request down a known chain — single-{post-type}.php, then single.php, then singular.php, then index.php — and your file runs, calls get_header(), runs The Loop, and prints markup you control character by character.

<?php get_header(); ?>
<main class="site-main">
  <?php while ( have_posts() ) : the_post(); ?>
    <h1><?php the_title(); ?></h1>
    <?php the_content(); ?>
  <?php endwhile; ?>
</main>
<?php get_footer(); ?>

Block themes use the same hierarchy names with .html extensions, but the file contains block markup — HTML with block delimiters in comments — and there are no template tags:

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main"} -->
<main class="wp-block-group">
  <!-- wp:post-title {"level":1} /-->
  <!-- wp:post-content /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Three consequences developers hit immediately:

get_header() and get_footer() never run. Anything hooked to those actions, in a plugin or an old child theme, silently does nothing. wp_head and wp_footer still fire, so most enqueueing survives, but header-specific hooks do not.

The database beats your files. The moment anyone saves a template in the Site Editor, WordPress stores that version as a wp_template post and serves it instead of your file. You can edit the HTML file all afternoon and see zero change on the front end. Clearing the customization for that template restores the file version. This is the single most common “my block theme is broken” report, and it is not a bug.

Styling moves into theme.json. Colors, spacing scale, typography, and per-block defaults are declared as data rather than CSS, and WordPress generates the CSS. It is cleaner and far more consistent — until you need something the schema does not express, at which point you are writing CSS anyway and fighting specificity against generated rules.

{
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "brand", "color": "#1a1a1a", "name": "Brand" }
      ]
    }
  }
}

Check the version value against the WordPress release you are on — the schema has revised more than once and copying a version number from an old tutorial produces settings that are quietly ignored.

Note that functions.php does not disappear. Block themes still use it for enqueueing, registering add_image_size entries, custom post types, and anything else PHP. You just do far less templating there.

What you actually gain, and what you actually lose

Going block gains you: editor control over the whole page, design consistency enforced by theme.json, fewer files to maintain, and styles that match between the editor and the front end far more often than classic themes ever managed.

Going block loses you: direct control of output markup, straightforward hook-based customization, compatibility with anything that assumes PHP templates, and the reassurance that the site’s appearance lives in version control.

That last one deserves emphasis. In a classic theme, git log tells you what changed. In a block theme, a meaningful share of the site’s appearance lives in the database where your deployment pipeline does not look.

When a classic theme is still the right answer

• A page builder runs the site. Elementor, Divi, Beaver Builder and similar tools take over templating themselves. Layering a block theme underneath adds a second templating system that does nothing.
• The markup has to be exact. Bespoke component libraries, strict accessibility markup, unusual schema requirements — block output is constrained by what blocks emit, and fighting it costs more than writing PHP.
• Heavy plugin templating. Membership, LMS, directory, and older commerce extensions frequently ship PHP template overrides. Many have block equivalents now; many do not.
• The site is finished and working. A theme with five years of accumulated customization has no upgrade path to block, only a rebuild. “It is the newer approach” is not a business reason.
• Nobody but you will edit it. The Site Editor’s main benefit is handing control to non-developers. If there are no non-developers, you are paying the costs for a benefit nobody uses.

The hybrid middle ground

A classic theme can add a theme.json and get the global styles system, the color and spacing presets, and consistent editor styling — while keeping its PHP templates and Customizer. WordPress does not call this a block theme, and the Site Editor stays unavailable, but you get most of the design-system benefit for a fraction of the work.

For an existing site that mostly works, this is usually the right first move. Add theme.json, define your palette and spacing, delete the CSS it replaces, and see whether you still want the rest.