A classic theme builds every page from PHP template files that a developer edits. A block theme builds every page from blocks, stored as HTML template files plus one configuration file, and lets an administrator edit those templates in the browser. The block themes vs classic themes decision is about who should be able to change the site's structure after launch, and how much PHP logic your templates carry.
Both kinds are fully supported by WordPress. What follows is how they differ in practice, where the hybrid approach fits, and how to choose for a new build or an existing site.
The difference starts in the theme folder
A classic theme is a set of PHP templates chosen by the template hierarchy, with shared pieces pulled in by get_header() and get_footer():
my-classic-theme/
style.css
functions.php
index.php
header.php
footer.php
single.php
page.php
archive.php
A block theme uses the same hierarchy, but the templates are HTML files containing block markup, and the reusable pieces are template parts:
my-block-theme/
style.css
theme.json
functions.php
templates/
index.html
single.html
page.html
parts/
header.html
footer.html
patterns/
styles/
According to the Theme Handbook's page on theme structure, only two files are required for WordPress to treat a theme as a block theme: style.css and templates/index.html. In practice theme.json does most of the work.
Block themes vs classic themes side by side
| Classic theme | Block theme | |
|---|---|---|
| Templates | PHP files | HTML files of block markup |
| Header and footer | header.php, footer.php | Template parts, editable in the Site Editor |
| Colors, fonts, spacing | CSS, plus Customizer options the theme registers | theme.json, plus the Styles panel |
| Menus and sidebars | Appearance > Menus and widget areas | Navigation block and blocks inside template parts |
| Who changes layout | A developer, in code | An administrator in the browser, or a developer in files |
| Dynamic logic | PHP directly in the template | Custom blocks, patterns or block bindings |
The last row is the one that decides most projects. In a classic template you can write any PHP you like between the markup. In a block template you cannot, so conditional output and custom queries have to be packaged as a block or a pattern.
What theme.json changes
theme.json holds two things. Settings define what editors are offered: the color palette, font sizes, spacing scale and layout widths, and which controls are switched off. Styles define the default appearance of the site, of elements such as headings and links, and of individual blocks. WordPress turns the presets into CSS custom properties and applies them in the editor and on the front end, so what editors see matches the live site.
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"color": {
"custom": false,
"palette": [
{ "slug": "primary", "name": "Primary", "color": "#0b3d91" },
{ "slug": "ink", "name": "Ink", "color": "#1c1c1c" }
]
},
"layout": { "contentSize": "720px", "wideSize": "1200px" }
}
}
That example limits editors to two brand colors and removes the free color picker. For a business site, this is the most useful property of the format: brand rules live in one file and the editor enforces them. The file is not exclusive to block themes. The handbook's introduction to theme.json states that it works with classic themes as well.
The Site Editor is a feature and a responsibility
With a block theme active, Appearance > Editor opens the Site Editor, where administrators edit templates, template parts, patterns and global styles. The Customizer, the Menus screen and the Widgets screen step aside, because their jobs have moved into blocks.
The detail that surprises teams is where edits go. A change made in the Site Editor is saved in the database and takes priority over the theme's file. Three consequences follow:
- If a developer later updates
parts/header.htmlin the theme, a site with a customized header keeps showing the database version until someone resets that part. - Staging and production drift apart when people edit templates on the live site.
- Version control no longer holds the whole design.
Agree on a rule early. Either structure is changed only in theme files and deployed, or changes made in the editor are exported back into the theme. The Create Block Theme plugin, published by WordPress.org, saves editor changes to the theme's files for that purpose. Template editing requires an administrator-level capability, so check who holds that role.
Hybrid themes put block features inside a classic theme
You do not have to choose all at once. A classic theme can adopt block features one by one, an approach the WordPress developer blog describes in its article on hybrid themes:
- Add a
theme.jsonto control editor settings and base styles while keeping every PHP template. - Register block patterns from a
/patternsfolder. - Declare
add_theme_support( 'block-template-parts' )so that pieces such as the footer become block template parts editors can change, while the page templates stay in PHP.
For an established site with years of template logic, this is usually the right first move. Editors gain consistent styles and patterns, and nothing is rewritten that already works.
Page builders and plugins change the answer
If the site is built with a page builder that has its own theme builder (Elementor, Divi and Beaver Builder all do), the builder supplies the header, footer and templates, and the theme underneath matters much less. Adding the Site Editor on top gives you two competing systems for the same job. Pick one and stay with it.
Plugins deserve a check as well. Anything that depends on classic theme features, such as widget areas, menu locations or Customizer settings, has no place to appear in a pure block theme. WooCommerce ships block templates for its store pages. For other large plugins, such as a WordPress LMS or a membership system, confirm block theme support with the vendor before committing.
Migrating a classic theme in stages
Switching themes does not alter post or page content, so the work is in templates and site-wide elements. An order that keeps the site working throughout:
- Inventory. List templates, widget areas, menus, Customizer settings, shortcodes and every piece of PHP logic inside templates.
- Go hybrid. Add
theme.jsonwith the current palette, type scale and widths. Fix the styling differences this causes in the editor. - Convert shared parts. Rebuild the header and footer as block template parts, and the menus as Navigation blocks.
- Convert templates one at a time, starting with the simplest. Turn each piece of template logic into a custom block or a pattern.
- Move widgets into template parts or patterns.
- Compare on staging. Check every template against the live site, including plugin output such as store and account pages.
- Switch, and keep the old theme installed until you are sure.
You can stop after step two or three and have a perfectly good hybrid theme.
Which to build on
For a new site without a page builder, start with a block theme. It is where WordPress core development is concentrated, the default themes have been block themes for several years, and brand control through theme.json is hard to match. Choose classic or hybrid when the templates carry heavy PHP logic, when a key plugin expects classic features, or when the team that maintains the site works in PHP templates and has no reason to change. A working classic theme is not a problem to be solved.
A small site can move to an existing block theme without a developer. A custom design, or a staged migration of a business site, is a WordPress theme development project, and the custom blocks that replace template logic are built as plugins, which makes them plugin development work. Agree on the palette, type scale and spacing before anyone writes theme.json. Our article on design systems for growing products covers that step.
Frequently asked questions
Are classic themes being discontinued?
No end date has been announced, and classic themes continue to work with current WordPress. New design features arrive in the block and site editors first, so the gap in editing tools grows over time, but there is no deadline that forces a move.
Can I use the block editor with a classic theme?
Yes. The block editor for posts and pages works with any theme. What a classic theme lacks is the Site Editor for templates, unless it opts in to individual features as a hybrid theme.
Will switching to a block theme break my content?
Post and page content stays as it is. What changes is everything around it: header, footer, menus, sidebars and template layouts need rebuilding, and shortcodes or widgets supplied by the old theme stop working. Test on a staging copy first.
Are block themes faster?
They can be lean, since they need no page builder framework and WordPress can load styles only for the blocks a page uses. Speed still depends on images, plugins, hosting and caching, and a well-built classic theme performs just as well.
Add worldwincoder.com as a preferred source on Google, or open this article in your AI assistant to use it as a source.

