Block themes vs classic themes in WordPress 7.1: which should you build?

If you are starting a WordPress project in late 2026, one of the first decisions is whether to build a block theme or a classic theme. Both are supported by WordPress 7.1.3, the current release, and both can produce fast, accessible sites. They differ in who can change the design, where templates live, and how much PHP your team writes.

This comparison explains how each type works, what WordPress 7.0 and 7.1 changed for theme developers, and which choice fits common situations: a brochure site handed to a client, a content-heavy publication, or an existing classic theme you need to keep running.

The short definitions

The WordPress Theme Handbook describes two primary theme types:

• Block themes are built from HTML templates that contain block markup. Users can edit every template in the Site Editor, and global settings and styles come from a theme.json file that users can adjust under Styles. The handbook calls them "the modern method of building WordPress themes" and focuses its documentation on them.
• Classic themes use PHP template files, the template hierarchy that dates back to WordPress 1.5, and the Customizer. They are still fully supported and still widely used.
• Hybrid themes are an informal term for classic themes that adopt some block features, such as a theme.json file or block template parts. Technically they remain classic themes.

How the files differ

A block theme needs only two files to be recognised: style.css with the theme header, and templates/index.html. The handbook notes that templates/index.html "is necessary for WordPress to consider this a block theme".

my-block-theme/
├── style.css            (required: theme header)
├── theme.json           (settings and styles)
├── functions.php        (optional)
├── templates/
│   ├── index.html       (required: fallback template)
│   ├── single.html
│   └── page.html
├── parts/
│   ├── header.html
│   └── footer.html
└── patterns/
    └── hero.php

A classic theme also needs style.css, with index.php as its fallback template, and normally splits markup into PHP partials:

my-classic-theme/
├── style.css            (required: theme header)
├── index.php            (required: fallback template)
├── functions.php
├── header.php
├── footer.php
├── single.php
├── page.php
└── template-parts/
    └── content.php

In a block theme, a template is block markup rather than PHP. A minimal templates/index.html that lists posts looks like this:

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

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
	<!-- wp:query {"queryId":1,"query":{"inherit":true}} -->
	<div class="wp-block-query">
		<!-- wp:post-template -->
			<!-- wp:post-title {"isLink":true} /-->
			<!-- wp:post-excerpt /-->
		<!-- /wp:post-template -->
		<!-- wp:query-pagination -->
			<!-- wp:query-pagination-previous /-->
			<!-- wp:query-pagination-next /-->
		<!-- /wp:query-pagination -->
	</div>
	<!-- /wp:query -->
</main>
<!-- /wp:group -->

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

There is no loop to write and no escaping to remember in the template itself: the core blocks (Query Loop, Post Title, Post Excerpt) handle the data and output. When you need logic that blocks cannot express, you write a custom block in a plugin and place it in the template.

Side-by-side comparison

What WordPress 7.0 and 7.1 changed for themes

The last two major releases added features that mostly benefit block themes, plus one change that affects every theme.

Responsive styles and configurable breakpoints (7.1)

WordPress 7.1 lets users and themes define styles for tablet and mobile viewports, both in Global Styles and on individual blocks, without custom CSS. In theme.json you add @mobile or @tablet keys inside a block's styles. Themes can also change the breakpoints with a new top-level settings.viewport setting:

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"settings": {
		"appearanceTools": true,
		"layout": {
			"contentSize": "720px",
			"wideSize": "1200px"
		},
		"viewport": {
			"mobile": "30rem",
			"tablet": "48rem"
		}
	},
	"styles": {
		"blocks": {
			"core/group": {
				"spacing": {
					"padding": {
						"top": "3rem",
						"right": "3rem",
						"bottom": "3rem",
						"left": "3rem"
					}
				},
				"@mobile": {
					"spacing": {
						"padding": {
							"top": "1rem",
							"right": "1rem",
							"bottom": "1rem",
							"left": "1rem"
						}
					}
				}
			}
		}
	}
}

According to the 7.1 developer note, the defaults are @mobile for widths up to 480px and @tablet for widths above 480px up to 782px. There is no @desktop key: the block's normal style is the base and applies at all sizes unless overridden. Breakpoints must be lengths in px, em or rem; percentages, unitless numbers and CSS functions are ignored. The same breakpoints drive the block visibility controls added in 7.0.

If you hand a site to a client and do not want them making per-device styling changes, 7.1 adds an editor setting to switch the interface off. Saved responsive styles still render.

<?php
add_filter( 'block_editor_settings_all', function ( $settings ) {
	$settings['responsiveEditingEnabled'] = false;
	return $settings;
} );

Pseudo-state styles (7.1)

Theme authors can now style :hover, :focus, :focus-visible and :active states through theme.json, and users can set hover, focus and active styles for Button blocks in the editor. Responsive and pseudo-states nest from viewport to state, for example "@mobile": { ":hover": { ... } }.

The post editor is always iframed (7.1)

This one matters for classic themes. Since WordPress 7.1 the post editor runs inside an iframe for all themes, matching the Site Editor. The release notes say admin styles no longer leak into the content and that viewport units and media queries now target the editing canvas. If your classic theme injected editor CSS or scripts that relied on reaching the admin document, test it in 7.1 and follow the iframe migration guidance in the block editor handbook.

Font management and other 7.0 additions

WordPress 7.0 added a dedicated font management page that works with block, hybrid and classic themes, block-level custom CSS, show/hide controls per device, and a navigation overlay built from blocks and patterns. These features reduce the number of small plugins a block theme needs.

theme.json is not only for block themes

theme.json version 3 is the current schema; the living reference says it works with WordPress 6.6 or later. A classic theme can ship a small theme.json to control the colour palette, font sizes and spacing presets that users see in the block editor, without adopting block templates. This is the usual first step towards a hybrid theme:

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"settings": {
		"color": {
			"palette": [
				{ "slug": "brand", "name": "Brand", "color": "#1d4ed8" },
				{ "slug": "ink", "name": "Ink", "color": "#111827" }
			]
		}
	}
}

Adding this file changes some editor defaults, so test existing content after adding it. Start with the settings you need, rather than copying a large file from another theme.

Which should you choose?

Choose a block theme when

• You are building a new site and the owner will make design changes after launch.
• The design can be expressed with core blocks, patterns and a few custom blocks.
• You want responsive adjustments, fonts and colours to be editable without a developer.
• You want to start from a default theme or a child of one and adjust it in the Site Editor.

Keep or build a classic theme when

• You maintain an existing classic theme that works; WordPress has not announced an end to classic theme support.
• Templates contain substantial custom PHP logic that would need to be rebuilt as blocks.
• The organisation needs the design locked, with content editors working only in posts.
• Plugins you depend on output templates that assume a classic theme.

Consider a hybrid step first when

• You want users to get a consistent palette and typography in the editor now, and a full move to block templates later.
• You want to try block template parts, such as a block-based footer, in one area before converting the whole theme.

A practical migration checklist

1. Inventory your PHP templates and note any that contain custom queries or business logic.
2. Move business logic (custom post types, shortcodes, integrations) into a plugin first. The handbook advises that themes control presentation and plugins control behaviour.
3. Add a theme.json with your palette, font sizes and layout widths.
4. Rebuild the header and footer as template parts, then the single and page templates.
5. Replace custom PHP output with core blocks or custom dynamic blocks.
6. Test in the 7.1 iframed editor, at mobile and tablet widths, and with keyboard-only navigation.

Summary

Block themes are where WordPress's design tooling is going: 7.1 added responsive styles, configurable breakpoints and pseudo-state styling, all driven by theme.json and the Site Editor. Classic themes remain supported and are the safer choice for heavily customised or locked-down projects, but they must now work with an iframed post editor. For many teams the sensible path is a classic theme with a small theme.json today, and block templates for new builds.