Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared Managed Cloud India
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Best lists Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Setup & site building · Explainer

Block Themes vs Classic Themes in WordPress

Short answer

A block theme builds its templates from blocks in HTML files and is edited in the Site Editor, while a classic theme builds its templates from PHP files and is edited through the Customizer, widgets, and menus. WordPress treats a theme as a block theme when it has a templates/index.html file. Pick a block theme for visual editing, or a classic theme when you need PHP logic in the templates.

Key takeaways

  • A block theme is defined by a templates/index.html file, while a classic theme uses PHP templates instead.
  • The Site Editor under Appearance > Editor only appears when a block theme is active.
  • theme.json version 3 is the latest format, and it works with WordPress 6.6 or later.
  • A theme.json file alone does not make a theme a block theme, since it also works in classic themes.
  • Twenty Twenty-Five is a block theme with 16 style variations, as listed on WordPress.org in November 2026.
  • Hybrid themes are classic themes with some block features, and hybrid is a community term, not an official type.

What is the difference between a block theme and a classic theme?

A block theme builds its layout from blocks in HTML template files, while a classic theme builds its layout from PHP template files.

That one file difference changes how you edit the site. A block theme opens the Site Editor, where you change the header, footer, and templates with blocks. A classic theme opens the Customizer and theme settings, and its layout lives in PHP code.

WordPress treats a theme as a block theme when it has a templates/index.html file. The Theme Structure page in the Theme Handbook lists style.css and templates/index.html as the two files WordPress needs to recognise a block theme.

AreaBlock themeClassic theme
TemplatesHTML files with block markup in templates/PHP files such as index.php and single.php
Whole-site editingSite Editor under Appearance > EditorCustomizer, widgets, and Menus screen
Design settingstheme.json plus style variationsfunctions.php, CSS, and theme settings
Header and footerTemplate parts in parts/PHP files such as header.php and footer.php
NavigationNavigation blockMenus registered in functions.php

What is a block theme?

A block theme is a theme whose templates are HTML files made of blocks, and whose design settings live in theme.json.

Every part of the site uses blocks in a block theme. The handbook says a block theme uses blocks for navigation menus, header, content, and site footer, and the Site Editor documentation adds that the Site Editor is only available when a block theme is active.

A block theme still needs a style.css file. That file holds the theme name and description that WordPress shows under Appearance > Themes, and it can also hold custom CSS.

What files does a block theme contain?

  • templates/index.html is the required fallback template.
  • templates/ also holds files such as 404.html, archive.html, and singular.html.
  • parts/ holds template parts such as header.html and footer.html.
  • patterns/ holds reusable block patterns that WordPress registers on its own.
  • styles/ holds style variations as JSON files.
  • theme.json holds global settings and styles.

The handbook lists a screenshot of 1200 by 900 pixels for the theme preview under Appearance > Themes. Both PNG and JPG files work for that screenshot.

Twenty Twenty-Five is a block theme, and its WordPress.org theme page lists it with the “Block theme” tag and 16 style variations as of November 2026.

What is a classic theme?

A classic theme is a theme whose templates are PHP files that WordPress picks through the template hierarchy.

PHP is the language those templates are written in. The PHP manual introduction describes PHP as a server-side scripting language, and classic themes use it to print each page with template tags such as the_title().

Classic themes expose settings in different places from block themes. They use the Customizer for live previews, widget areas for sidebars, and the Menus screen for navigation. The Theme Handbook notes that sidebars, custom headers, and custom backgrounds are classic theme features.

Menus show the split clearly. In a classic theme, you register menus with register_nav_menus() in functions.php and print them with wp_nav_menu(). In a block theme, you use the Navigation block instead, as the Theme Functions page explains.

Classic themes still support the block editor for posts and pages. The difference is only in how the theme itself is built and how the header, footer, and templates are changed. If you want a plain-language split between the two parts of a site, read themes vs plugins in WordPress.

How does the Site Editor work in a block theme?

The Site Editor lets you design the whole site with blocks, including the header, footer, and everything between them.

You open it from Appearance > Editor after you activate a block theme. WordPress.org's documentation states that the Site Editor is only available when a block theme is installed and activated.

Once you enter the Site Editor, you will see five menu items in its navigation. The editor opens on a preview of your site, with a sidebar for moving between templates, template parts, and other parts of the site.

The Template Editor is a smaller piece of the same idea. It lets you edit and create templates with blocks, and it works with a block theme or with a classic theme that has enabled it, according to the Template Editor documentation.

Page builders are a separate choice from the theme type. A block theme works with the built-in editors, while a builder adds its own canvas. See Gutenberg vs Elementor for how those two editors compare.

What is theme.json and how does it fit in?

theme.json is a configuration file that sets global settings and styles for a theme, such as colours, fonts, spacing, and layout widths.

Version 3 is the latest version of theme.json, and it works with WordPress 6.6 or later. The theme.json Version 3 Reference is the living specification for that version.

A common mix-up is treating theme.json as proof of a block theme. It is not. The Introduction to theme.json states that the file works with both block and classic themes.

In a block theme, theme.json is often the most important file. The same introduction calls it the foundational piece that feeds into every other component of a block theme.

What can you set in theme.json?

  • Colour palettes, gradients, and duotone presets for the colour picker.
  • Font families, font sizes, and fluid typography settings.
  • Spacing sizes, margins, padding, and the gap between blocks.
  • Layout widths, including contentSize for normal content and wideSize for wide content.
  • Which editing controls appear for each block.

The reference also lists default viewport breakpoints of 480 pixels for mobile and 782 pixels for tablet. Those defaults shape responsive block styles, and the responsive design basics guide from web.dev explains how layouts adapt to different screen widths.

Style variations build on theme.json. Each variation is a JSON file in the styles/ folder, and it changes the colours, fonts, and spacing of the whole site in one switch.

Block bindings are a related feature for showing live values from custom fields inside blocks. If your theme needs that, read how to use block bindings in WordPress.

What is a hybrid theme?

A hybrid theme is a classic theme that has adopted some block features, such as a theme.json file or block template parts.

“Hybrid theme” is a community term, not an official third type. WordPress still treats the theme as classic unless it has the template files that make it a block theme.

This middle ground is common in practice. Many long-running themes started as classic themes and added theme.json settings for the block editor without rebuilding their PHP templates.

The test stays simple. If the theme has templates/index.html, WordPress treats it as a block theme. If it only has a theme.json file, it stays classic.

How do you tell which type of theme your site uses?

Open Appearance in your WordPress dashboard and look at the menu items you see.

If you see Editor under Appearance, you are using a block theme. If you see Customize, Widgets, and Menus instead, you are using a classic theme.

You can also check the theme files. Go to Appearance > Themes, note the active theme name, then look in wp-content/themes/ for that theme folder. A templates/index.html file means a block theme, while index.php at the theme root with no templates/ folder means a classic theme.

The theme directory also labels block themes. When you browse Appearance > Themes > Add New, you can filter by Block Themes to see only block themes, as the Site Editor documentation explains.

Which type should you choose for a new site?

Choose a block theme if you want to edit the header, footer, and templates yourself with blocks and no code.

A block theme suits blogs, brochure sites, and small business sites where the owner will change layouts. The Site Editor, style variations, and patterns cover most design changes without a developer.

Choose a classic theme if your site needs PHP logic in its templates, such as conditional layouts or deep hooks and filters. A classic theme also fits when you are keeping an existing classic build or when a plugin you rely on works only with classic theme features.

Cost is a separate question from type. Both free and paid themes exist in each type, so compare them on their own terms. Our guide to free vs premium WordPress themes explains what the price usually covers.

If you plan to hire a developer for a one-off design, check how much a custom WordPress theme costs before you pick a starting point.

What happens to your content if you switch theme types?

Switching themes changes the layout, not your posts and pages.

What changes is the layout around that content. A block theme shows your content through its templates and style variations, while a classic theme shows it through its PHP templates and Customizer settings.

Some settings do not carry over. Menu locations, widget areas, and Customizer choices belong to the old theme, so you may need to set them again in the new theme.

Before you switch, take a full backup and preview the new theme first. Check the header, footer, menus, and a few key pages before you activate it for visitors. The Work with themes documentation covers adding and switching themes from the dashboard.

What mistakes should you avoid?

Most mistakes come from judging a theme by one file or one setting instead of checking how WordPress actually treats it.

  • Do not assume a theme is a block theme because it has a theme.json file. Check for templates/index.html instead.
  • Do not expect the Site Editor in a classic theme. It only appears with a block theme.
  • Do not edit the parent theme files directly to change a design. Use the Site Editor or a child theme so your changes survive theme updates.
  • Do not pick a type based on speed claims alone. No official source in this guide ranks one type as faster than the other.
  • Do not switch themes on a live site without a backup and a preview first.

Frequently asked questions

Can I use the block editor with a classic theme?

Yes. The block editor for posts and pages works with both theme types. What changes is the rest of the site: only a block theme gives you the Site Editor for headers, footers, and templates, while a classic theme keeps those parts in PHP files and the Customizer.

Is a block theme better for SEO than a classic theme?

No. The difference between the two types is in templates and editing tools, not in search features. Pick the type that fits how you will edit the site, then handle SEO with good content, clear structure, and sensible site settings.

Do block themes need extra plugins to work?

No. WordPress core provides the Site Editor, patterns, style variations, and theme.json support for block themes. You may still add plugins for features such as forms or shops, but the theme itself does not need a plugin to edit the whole site.

Can I convert a classic theme into a block theme?

There is no one-click converter in WordPress core. You rebuild the templates as HTML block templates in a templates folder, or you keep the classic theme and add block features such as a theme.json file. For a live site, build the new theme separately and preview it before switching.

Are classic themes still supported?

Yes. Classic themes remain a supported way to build WordPress themes, and the Theme Handbook still documents them. New block features also reach classic themes: a theme.json file works in a classic theme, so a classic theme can offer modern editor controls without becoming a block theme.

Which theme should I try first to learn block themes?

Twenty Twenty-Five is a good starting point. It is a block theme listed on WordPress.org with 16 style variations, so you can open the Site Editor, switch styles, and see how templates, template parts, and theme.json work together on a real theme.

Sources

  1. Site Editor WordPress.org Documentation
  2. Theme Structure WordPress Developer Resources
  3. Theme.json Version 3 Reference (latest) WordPress Developer Resources
  4. Introduction to theme.json WordPress Developer Resources
  5. Twenty Twenty-Five WordPress.org Themes
  6. Template Editor WordPress.org Documentation
  7. Work with themes WordPress.org Documentation
  8. theme.json schema (version 3) WordPress.org

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

WPLegible editors

Researched from the primary sources listed above and checked against our editorial rules. About the site · How we test