What are block themes in WordPress?

Block themes are WordPress themes built entirely out of blocks. Instead of PHP template files like header.php and single.php, a block theme uses HTML templates made of block markup and a theme.json file for settings and styles. This lets you edit every part of your site, from the header to the 404 page, visually in the Site Editor.

Block themes are the foundation of Full Site Editing and the direction WordPress core has been moving for several years. In this article, you'll learn what block themes are, how they differ from classic themes, what files they contain, how to tell which kind of theme you're using, and how to decide whether a block theme is right for your next project.

What Is a Block Theme?

A WordPress theme controls how your site looks and how content is laid out. For most of WordPress's history, themes were written in PHP. A theme developer would write a header.php file with HTML and template tags, a footer.php file, a single.php file for posts, and so on. As a site owner, you could only change what the developer exposed through the Customizer.

A block theme takes a different approach. Every template is made of blocks, the same blocks you use in the post editor. The header is a template part made of Site Logo, Site Title, and Navigation blocks. The blog listing is a template containing a Query Loop block. The single post template uses Post Title, Post Featured Image, and Post Content blocks.

Because everything is blocks, WordPress can offer a visual editor for all of it. That editor is the Site Editor, located at Appearance > Editor.

Block themes were introduced alongside WordPress 5.9, with Twenty Twenty-Two as the first default block theme. Since then, Twenty Twenty-Three, Twenty Twenty-Four, and Twenty Twenty-Five have followed, and the WordPress.org theme directory now has a large and growing collection of block themes.

Block Themes vs. Classic Themes

The easiest way to understand block themes is to compare them with classic themes.

Templates: Classic themes use PHP files (index.php, single.php, page.php). Block themes use HTML files (templates/index.html, templates/single.html) containing block markup.

Design settings: Classic themes register options through the Customizer at Appearance > Customize. Block themes use theme.json and Global Styles in the Site Editor.

Headers and footers: Classic themes hard-code them in header.php and footer.php. Block themes use editable template parts in a parts folder.

Menus: Classic themes use Appearance > Menus and wp_nav_menu(). Block themes use the Navigation block.

Widgets: Classic themes provide widget areas (sidebars). Block themes have no widget areas; you add blocks directly into templates.

Editing: Classic themes need code changes (ideally in a child theme) for layout changes. Block themes let you change layouts visually, and store those changes in the database.

Neither type is "wrong." Classic themes are still fully supported, and millions of sites run on them. But new WordPress features, especially design tools, are built with block themes in mind.

What's Inside a Block Theme?

A block theme can be surprisingly small. Here's a typical folder structure:

my-block-theme/
├── style.css
├── theme.json
├── functions.php        (optional)
├── screenshot.png
├── templates/
│   ├── index.html
│   ├── single.html
│   ├── page.html
│   ├── archive.html
│   ├── search.html
│   └── 404.html
├── parts/
│   ├── header.html
│   └── footer.html
├── patterns/
│   └── hero.php
└── styles/
    └── dark.json        (style variation)

Let's look at the most important pieces.

style.css

Every theme still needs a style.css file with a header comment. WordPress reads this to get the theme's name, version, and other details:

/*
Theme Name: My Block Theme
Theme URI: https://example.com/
Author: Your Name
Description: A simple block theme.
Requires at least: 6.4
Tested up to: 6.8
Requires PHP: 7.4
Version: 1.0.0
License: GNU General Public License v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-block-theme
*/

In a block theme, style.css often contains little or no actual CSS, because most styling lives in theme.json.

templates/index.html

The one template WordPress requires in a block theme is templates/index.html. Its presence is actually how WordPress detects that a theme is a block theme. A minimal version might look 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":{"perPage":10,"postType":"post","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-numbers /-->
    <!-- wp:query-pagination-next /-->
    <!-- /wp:query-pagination -->
  </div>
  <!-- /wp:query -->
</main>
<!-- /wp:group -->

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

The HTML comments like <!-- wp:post-title /--> are block delimiters. WordPress parses them and renders each block, pulling in dynamic content such as post titles.

parts/header.html and parts/footer.html

Template parts are reusable sections. A simple header might contain:

<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
<div class="wp-block-group">
  <!-- wp:site-title /-->
  <!-- wp:navigation /-->
</div>
<!-- /wp:group -->

theme.json

The theme.json file is the control center of a block theme. It defines the color palette, font families and sizes, spacing scale, content widths, and default styles for blocks. It also decides which design controls users see in the editor. Here's a small example:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "base", "color": "#ffffff", "name": "Base" },
        { "slug": "contrast", "color": "#111111", "name": "Contrast" },
        { "slug": "accent", "color": "#2563eb", "name": "Accent" }
      ]
    },
    "layout": {
      "contentSize": "680px",
      "wideSize": "1200px"
    }
  },
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--contrast)"
    }
  }
}

WordPress turns these settings into CSS custom properties like --wp--preset--color--accent, which you can use anywhere in your styles.

patterns/

Block themes often ship patterns, which are ready-made block layouts like hero sections or call-to-action areas. Any PHP file in the patterns folder with the right header comment is registered automatically.

styles/

The styles folder holds style variations: alternate JSON files that override parts of theme.json. Users can switch between them in Appearance > Editor > Styles, for example to change from a light palette to a dark one.

How to Tell If Your Theme Is a Block Theme

There are a few quick ways to check:

1. Look at the Appearance menu: If you see Appearance > Editor and no Customize or Widgets item, you're almost certainly using a block theme.

2. Check the theme's files: If the theme folder contains templates/index.html, it's a block theme.

3. Check the theme directory listing: On WordPress.org, block themes are tagged with "Full Site Editing."

4. Use code: WordPress provides the wp_is_block_theme() function, which returns true when the active theme is a block theme. Developers can use it in a plugin to adjust behavior:

add_action( 'admin_notices', 'sajjad_block_theme_notice' );

function sajjad_block_theme_notice() {
if ( ! current_user_can( 'manage_options' ) ) {
return;
}

$message = wp_is_block_theme()
? __( 'Your active theme is a block theme.', 'sajjad' )
: __( 'Your active theme is a classic theme.', 'sajjad' );

printf(
'<div class="notice notice-info"><p>%s</p></div>',
esc_html( $message )
);
}

What About Hybrid Themes?

Between classic and block themes sits a middle ground sometimes called "hybrid" or "universal" themes. These are classic PHP themes that adopt some block features, such as a theme.json file for editor settings, block template parts, or support for block-based widgets. They let developers modernize gradually without rewriting the whole theme.

A classic theme can add theme.json to control the editor's color palette and font sizes, but it won't get the full Site Editor with editable templates unless it becomes a block theme. Since WordPress 6.3, classic themes can also give users access to the Patterns section of the Site Editor.

Benefits of Block Themes

Visual control over everything: You can edit headers, footers, and templates without code or a child theme.

Less reliance on plugins: Many layout tasks that used to require a page builder can be done with core blocks.

Consistent design system: theme.json defines colors, typography, and spacing in one place, and every block follows it.

Performance: Block themes typically load CSS only for the blocks present on the page and don't need heavy framework code. Results still depend on your plugins, images, and hosting.

Style variations: Switch the look of your whole site with a click.

Easier customization for clients: Site owners can make safe changes themselves, and any template can be reset to its original version.

Aligned with WordPress's future: New features like pattern overrides, block bindings, and design tools land in block themes first.

Drawbacks and Considerations

Block themes aren't the best fit for every situation:

• Plugin compatibility: Some older plugins rely on widget areas, Customizer settings, or classic theme hooks such as get_sidebar(). Most popular plugins now support block themes, but check before switching.
• Switching an existing site: Moving from a classic theme to a block theme means rebuilding headers, footers, and menus. Widgets and Customizer settings don't transfer automatically.
• Learning curve: Users coming from page builders or the Customizer need time to learn the Site Editor.
• Highly custom functionality: Complex dynamic layouts may need custom blocks or PHP, just as they would with a classic theme.

How to Choose a Block Theme

If you've decided to try a block theme, here are some tips for picking one:

1. Start with a default theme: Twenty Twenty-Five is well maintained, fast, and packed with patterns and style variations.

2. Browse the Full Site Editing tag: In Appearance > Themes > Add New Theme, use the Feature Filter and select "Full Site Editing."

3. Check patterns and style variations: A good block theme includes plenty of patterns for common sections and several style variations.

4. Look at update history and reviews: Choose themes that are updated regularly and tested with the latest WordPress version.

5. Test on staging: Before activating on a live site, install the theme on a staging copy and check your key pages and plugins.

If you want to build your own, the free Create Block Theme plugin from the WordPress team lets you create a new blank block theme, or a child theme of an existing one, and save Site Editor changes back into theme files.

---

FAQ: Block Themes in WordPress

---

Conclusion

Block themes represent the modern way to build WordPress sites. By replacing PHP templates with block-based HTML templates and centralizing design in theme.json, they let you control every part of your site visually through the Site Editor. They are simpler to customize, easier to keep consistent, and aligned with where WordPress development is heading.

If you're starting a new site in 2026, a block theme is a strong default choice. If your current site runs on a classic theme, there's no pressure to switch immediately, but it's worth trying a block theme on a staging site to see how it fits your workflow. Start with a default theme like Twenty Twenty-Five, explore the Site Editor, and you'll quickly see what makes block themes so flexible.