Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
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
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Explainers · Explainer

What Is a Block Theme? A Plain Explanation

What Is a Block Theme? A Plain Explanation

Short answer

A block theme is a WordPress theme built entirely from blocks, with HTML templates and a theme.json file instead of PHP template files. It lets you edit the header, footer, and page layouts in the Site Editor. Block themes need WordPress 5.9 or newer.

Key takeaways

  • A block theme builds every layout from blocks, so the header and footer are editable in the Site Editor.
  • It needs only 3 files: templates/index.html, style.css, and theme.json.
  • Block themes need WordPress 5.9 or newer, and theme.json version 3 arrived in WordPress 6.6.
  • theme.json sets colors, fonts, spacing, and layout widths in one structured file.
  • Site Editor changes are saved in the database, not in the theme files.
  • Classic themes use PHP template files, while block themes use HTML files made of blocks.

What is a block theme?

A block theme is a WordPress theme built entirely from blocks, with HTML templates and a theme.json file instead of PHP template files.

The Theme Developer Handbook states that a block theme is a new type of theme you can use from WordPress version 5.9, and it is built mainly with HTML and a theme configuration file. That change matters because the whole site, not just posts and pages, becomes editable with blocks.

Before 5.9, themes controlled the header, footer, and page layouts with PHP files that most site owners could not edit without code. A block theme moves those layouts into HTML template files made of blocks. You can change them in the admin area instead of editing files on the server.

WordPress 7.1.5, released on November 18, 2026, is the current version as of November 2026, and block themes work in every version from 5.9 onward. The idea has had years to settle, so the tools around it are stable now.

How does a block theme work?

A block theme stores each page layout as an HTML file that contains block markup, and WordPress renders that markup when a visitor loads the page.

When someone visits a post, WordPress picks a template from the theme, such as single.html, and fills in the post content, title, and date.

The template itself is a set of blocks, so a header block, a post title block, and a post content block sit in a fixed order. Your edits in the Site Editor change which blocks appear and how they are set.

Changes you make in the Site Editor are saved in the database, not in the theme files.

That split is useful: the theme files stay as the starting point, and your saved edits sit on top of them. If you switch themes, the Site Editor changes tied to the old theme do not follow you.

The Site Editor lives at “Appearance” then “Editor” in the admin menu. From there you can open templates, template parts, patterns, and styles without touching a file.

What files does a block theme need?

A block theme needs only 3 files to work, according to the Theme Developer Handbook page on your first theme.

Those 3 files are templates/index.html, style.css, and theme.json. The index.html file is the main template that lists posts, style.css holds the theme header and styles, and theme.json sets style properties in a structured way. A real theme adds more files, but those 3 are the minimum.

File or folderWhat it holdsRequired?
templates/index.htmlMain template that lists postsYes
style.cssTheme header and stylesYes
theme.jsonSettings, colors, fonts, and layout widthsYes
templates/Extra templates such as single.html and page.htmlNo
parts/Reusable parts such as header.html and footer.htmlNo
patterns/Ready-made block layouts you can insertNo
styles/Style variations that change the look in one clickNo

The handbook example sets a content width of 840 pixels and a wide width of 1100 pixels in theme.json. Those two numbers show how a theme controls layout with plain values instead of CSS rules.

Template parts deserve a note. A header or footer saved as a template part can be used on every template, so one edit updates the whole site. That is the block theme answer to the old header.php and footer.php files.

How is a block theme different from a classic theme?

A block theme builds layouts from blocks in HTML files, while a classic theme builds them from PHP files with template tags.

The Theme Developer Handbook puts it plainly: a classic theme is the original theme type, without version limits, that primarily uses PHP, JavaScript, and CSS.

A block theme is composed entirely of blocks, which lets you edit all parts of your site in the Site Editor. That one difference changes who can change a layout.

With a classic theme, moving a header menu or changing a footer layout usually means editing a PHP file or adding a filter in functions.php.

With a block theme, you open the Site Editor, click the header, and move the block. The trade is control: PHP can do things blocks cannot, so developers who need deep custom logic still pick classic themes for some projects.

Our guide on block themes vs classic themes compares the two side by side, including when each one fits.

FeatureBlock themeClassic theme
TemplatesHTML files with blocksPHP files with template tags
Header and footer editingSite Editor, no codePHP files or Customizer
Style settingstheme.json fileCSS files and theme options
Needs WordPress5.9 or newerAny version
Best forSite owners who edit layouts visuallyDevelopers who need PHP logic

What is theme.json and what does it do?

theme.json is the file that sets a block theme's colors, font sizes, spacing, and layout widths in one structured place.

WordPress 5.8 introduced theme.json as a new way to configure the editor, according to the Block Editor Handbook page on global settings and styles.

It gives the theme a single place to define which color palettes, font sizes, and layout widths the editor offers. Before it existed, themes set those options with separate theme support flags.

The current format is version 3, which arrived in WordPress 6.6. Older versions still work, and the handbook notes that new features are built on the latest version. If you open a theme and see "version": 3 at the top of theme.json, it uses the current format as of November 2026.

Presets in theme.json turn into CSS custom properties. A color named black becomes --wp--preset--color--black, and a class such as has-black-color becomes available too. That link between settings and CSS is why changing a palette color in one place updates every block that uses it.

Our guide on how to use theme.json walks through the settings section by section.

How do you edit a block theme on your site?

You edit a block theme in the Site Editor, under “Appearance” then “Editor”, where templates, template parts, and styles are all listed.

Open the Site Editor and pick “Templates” to see every layout the theme ships, from the front page to the 404 page.

Pick a template to edit its blocks, or pick “Template Parts” to edit the header or footer once for the whole site. The “Styles” panel changes colors, fonts, and spacing for the entire site.

Style variations live in the theme's styles/ folder as extra JSON files. Picking one in the Styles panel swaps the look without changing any content. That is a fast way to try a dark style or a different palette before you commit to it.

Patterns are another shortcut. A pattern is a ready-made arrangement of blocks, such as a hero section or a pricing table, that you insert and then edit. Our guide on how to use block patterns in WordPress shows where to find them and how to save your own.

How do you check if your theme is a block theme?

Open the Site Editor menu, and if you see “Appearance” then “Editor” with templates and styles, your theme is a block theme.

Classic themes show “Appearance” then “Customize” instead, and they open the Customizer rather than the Site Editor. That menu difference is the quickest check, and it works without reading any files.

You can also check the theme folder. A block theme has a templates/ folder with an index.html file inside it.

The handbook states that a theme with an index.html template in the templates/ folder counts as a block theme, and full site editing is enabled for it in WordPress 5.9 and later. If the folder holds only PHP files such as index.php and header.php, the theme is classic.

A third check is the theme page on WordPress.org, which lists the theme type in its details. That helps when you are choosing a theme before you install it.

What mistakes should you avoid with block themes?

Do not edit the theme files directly to change a layout, because your edits will vanish when the theme updates.

The safe route is to make layout changes in the Site Editor, or to build a child theme if you need file changes that survive updates.

The Learn WordPress lesson on child themes shows how a child theme holds only your changes while the parent keeps working. That lesson uses Twenty Twenty-Four as its example, with a child folder named twentytwentyfourchild.

Another mistake is to assume a block theme has no code at all. Block themes can still ship a functions.php file for small features, and many do. The file is optional, not banned, so check for it before you decide the theme does nothing in PHP.

Do not mix up patterns and templates either. A pattern is a block layout you insert into a page, while a template is the layout of a whole page type. Editing a pattern changes only the places you inserted it, but editing a template changes every page that uses it.

Our guide on how to create a block theme from scratch covers the file setup in full.

Our guide on how to edit the header in a block theme covers the most common first edit.

Frequently asked questions

Do I need to know code to use a block theme?

No. You edit layouts in the Site Editor by moving blocks, changing text, and picking colors and fonts. Code helps only when you want custom features that blocks cannot do, and most site owners never need it.

Can I switch from a classic theme to a block theme?

Yes, but treat it as a rebuild, not a simple switch. Your posts and pages stay, yet the header, footer, menus, and widget areas come from the new theme. Check every template in the Site Editor before you make the switch live.

Is a block theme faster than a classic theme?

Not by itself. Speed depends on the theme code, the plugins, the images, and the hosting. A light block theme can be fast, and a heavy one can be slow, so judge the theme, not the type alone.

What happens to my Site Editor changes if I change themes?

They stay tied to the old theme and do not carry over. Your content stays safe, but the layouts, styles, and template edits from the old theme stop applying. Export or note your settings first if they matter.

Do block themes work with page builders?

Most page builders work on block themes for page content, since they run inside the content area. The header and footer still belong to the theme, so check the builder docs before you plan a layout that mixes the two.

Sources

  1. Global Settings and Styles (theme.json) WordPress Developer Resources
  2. Your First Theme WordPress Developer Resources
  3. Child Themes WordPress Developer Resources
  4. Version 7.1.5 WordPress.org
  5. Child themes Learn WordPress
  6. Gutenberg GitHub

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

Written and checked byWPLegible Editorial Team Independent WordPress reviews and guides

Researched from the primary sources listed above and checked against our editorial rules before publishing.