Block theme
A block theme is a WordPress theme built entirely from blocks, so the header, the footer and the layout of every page are edited on screen in the Site Editor. A classic theme builds them in PHP files and is set up in the Customizer.
- By
- WP Ministry
- Published
In short
- If the Appearance menu has "Editor", the site uses a block theme. If it has "Customize", "Widgets" and "Menus", it uses a classic theme.
- On a block theme, the header, the footer and the page layouts are templates and template parts made of blocks, edited in the Site Editor.
- Instructions written for one kind of theme do not fit the other. Check which kind you have before you follow a tutorial.
A block theme is a WordPress theme in which every part of the site is made of blocks: the content of a page, and also the header, the navigation, the footer and the layout around them. Block themes arrived in WordPress 5.9. The older kind is called a classic theme.
The two are built and edited differently:
| Block theme | Classic theme | |
|---|---|---|
| Page layouts | Templates: HTML files of block markup | PHP template files |
| Header and footer | Template parts, also made of blocks | PHP files |
| Colors, fonts and spacing | theme.json, changed on screen under "Styles" | The Customizer and the theme's stylesheet |
| Where you edit | The Site Editor | The Customizer |
| Menus and sidebars | Blocks, such as the Navigation block | The Menus and Widgets screens |
Where you meet it
- The Site Editor. Go to Appearance, then Editor. That menu item is there only while a block theme is active. "Templates" holds the layouts, such as the one for a single post or the 404 page. "Patterns" holds the template parts, such as the header and the footer. "Styles" holds colors and fonts for the whole site.
- The theme's folder. A block theme has a
templatesfolder with files such asindex.htmlandsingle.html, apartsfolder withheader.htmlandfooter.html, and atheme.jsonfile. WordPress treats a theme as a block theme when it hastemplates/index.html. theme.json. This file sets which design controls the editor offers, and the theme's own colors, fonts and spacing. What you change under "Styles" is laid over it.
What goes wrong
A tutorial does not match your screen. Steps that begin "go to Appearance, then Customize", or that send you to Widgets or Menus, are for a classic theme. On a block theme the Customizer is hidden unless a plugin needs it. Adding CSS is the usual case: how to add custom CSS gives the place for each kind.
A template you edited no longer follows the theme. A change saved in the Site Editor is stored in the database and takes precedence over the theme's own file. A theme update does not overwrite it, and does not reach that template either, until you choose "Reset" on it. For changes kept in files, see how to create a child theme.
A fix depends on the kind of theme. Fonts are one example: a block theme declares them in theme.json, and a classic theme usually loads them from a stylesheet. The guide to fixing layout shift gives both.
You are leaving a page builder. Switching from Elementor to the block editor compares the two kinds for that move.
How to look at yours
Open the Appearance menu in the dashboard.
- Block theme: it lists "Themes" and "Editor".
- Classic theme: it lists "Themes", "Customize", "Widgets" and "Menus", and has no "Editor". In its place there may be "Design" or "Patterns".
Other items vary with the WordPress version and the theme. "Theme File Editor", under Appearance or Tools, is something else: it opens the theme's code files.
Common questions
Is a block theme the same as the block editor?
No. The block editor is where you write posts and pages, and it works with either kind of theme. A block theme extends blocks to the header, the footer and the templates.
Can I still use the Customizer with a block theme?
Normally not. WordPress hides it on a block theme, because the Site Editor does the same job with blocks. It appears again when a plugin or the theme itself needs it.
What is theme.json?
A file in the theme's folder that sets the theme's colors, fonts and spacing, and which design controls the editor shows. It is the base that the "Styles" panel changes. In a child theme, a theme.json of its own overrides the parent's values.