Gutenberg Times: How WordPress decides a theme is a “block theme”

The term “block theme” is used a lot in WordPress but it was never really clear to me what that meant exactly from a code point of view.

While researching The post editor is going full iframe: what block developers need to know before WordPress 7.1, I learned that the outcome of testing WordPress 7.1 Beta 1 may soften the plan: instead of forcing the iframe for everyone, core might force it only for block themes, while classic themes using blocks with apiVersion 2 or lower keep the current 7.0 behavior. (The linked article covers the 7.0 state of things in full.)

If that’s the split, then the exact definition of “block theme” suddenly matters a great deal. So what does core actually check?

The public API is wp_is_block_theme(), which just asks the active theme:

// wp-includes/theme.php (guard clause trimmed)
function wp_is_block_theme() {
	return wp_get_theme()->is_block_theme();
}

// wp-includes/theme.php (guard clause trimmed)
function wp_is_block_theme() {
	return wp_get_theme()->is_block_theme();
}

And WP_Theme::is_block_theme() is, in its entirety, a file-existence check:

// wp-includes/class-wp-theme.php (caching trimmed)
public function is_block_theme() {
	$paths_to_index_block_template = array(
		$this->get_file_path( '/templates/index.html' ),
		$this->get_file_path( '/block-templates/index.html' ),
	);

	foreach ( $paths_to_index_block_template as $path ) {
		if ( is_file( $path ) && is_readable( $path ) ) {
			return true;
		}
	}

	return false;
}

// wp-includes/class-wp-theme.php (caching trimmed)
public function is_block_theme() {
	$paths_to_index_block_template = array(
		$this->get_file_path( '/templates/index.html' ),
		$this->get_file_path( '/block-templates/index.html' ),
	);

	foreach ( $paths_to_index_block_template as $path ) {
		if ( is_file( $path ) && is_readable( $path ) ) {
			return true;
		}
	}

	return false;
}

A theme is a “block theme” if it ships an index.html block template, either in templates/, or in block-templates/, the pre-5.9 legacy location. Nothing else is consulted. That has a few consequences that may surprise people:

theme.json doesn’t make you a block theme. Neither do patterns, block template parts, or add_theme_support( 'block-templates' ). A theme can adopt every one of those “hybrid” features and still land on the classic side of this check, because the test only looks for a top-level index.html template.

Child themes inherit the answer. get_file_path() looks in the child theme first and falls back to the parent, so a child theme of a block theme is a block theme even if the child ships no templates of its own.

It’s a filesystem check, not a declaration. There’s no header in style.css that opts you in or out. Drop a templates/index.html into a theme and, as far as WordPress is concerned, it is a block theme.

The minimum files required for block and classic themes

This is the entire minimum viable block theme — two files:

my-block-theme/
├── style.css          ← standard theme header
└── templates/
    └── index.html     ← this file IS the decider

my-block-theme/
├── style.css          ← standard theme header
└── templates/
    └── index.html     ← this file IS the decider

(WordPress considers a theme valid if it has style.css plus either index.php or templates/index.html, which means for a block theme, index.php, functions.php, and even theme.json are all optional.)

And this is a theme that is guaranteed to stay classic:

my-classic-theme/
├── style.css
└── index.php          ← the classic fallback template

my-classic-theme/
├── style.css
└── index.php          ← the classic fallback template

Staying on the classic side of the check comes down to two conditions:

1. No templates/index.html and no legacy block-templates/index.html. Other block templates don’t matter: a theme with `templates/single.html` but no `templates/index.html` still tests as classic. (In practice, though, if you’re shipping block templates, ship the index and be a block theme on purpose.)
2. No block-theme parent. The check falls back to the parent theme, so a child of Twenty Twenty-Five is a block theme no matter what the child contains. To be classic, the whole chain has to be.

Everything else is fair game. theme.json, patterns, add_theme_support( 'block-template-parts' )` custom templates registered from plugins — none of them flip the switch., patterns, add_theme_support( 'block-template-parts' ), custom templates registered from plugins: none of them flip the switch.

Where real themes land

Running that check against some current releases from the theme directory

Six of the themes in the first column ship theme.json, the marquee “block” feature, and still test classic, because the check never looks at theme.json

Twenty Twenty and OceanWP are another good gotcha: both ship a templates/ directory and are still classic, because it’s full of PHP page templates (template-cover.php, landing.php). The check wants templates/index.html specifically, so “does it have a templates folder” is not the indicator you might assume.

How the editor reads it

On the JavaScript side, the block-theme flag surfaces in two different places, which is worth knowing if you go source-diving.

As an editor setting:

// wp-includes/block-editor.php, get_block_editor_settings()
$editor_settings['__unstableIsBlockBasedTheme'] = wp_is_block_theme();

// wp-includes/block-editor.php, get_block_editor_settings()
$editor_settings['__unstableIsBlockBasedTheme'] = wp_is_block_theme();

and on the REST themes endpoint, which is where @wordpress/core-data picks it up:

// wp-includes/rest-api/endpoints/class-wp-rest-themes-controller.php
$data['is_block_theme'] = $theme->is_block_theme();

// wp-includes/rest-api/endpoints/class-wp-rest-themes-controller.php
$data['is_block_theme'] = $theme->is_block_theme();

The one-file switch

For all the weight the term carries, “block theme” boils down to a single file: templates/index.html exists, or it doesn’t. Not theme.json, not patterns, not any amount of hybrid adoption. Just one index template, checked up the parent chain.

That’s worth keeping in mind if 7.1 does end up drawing the iframe line at wp_is_block_theme(). A hybrid theme that has adopted everything except block templates would keep the classic editor behavior, while adding a single templates/index.html (even accidentally, even in a parent theme you don’t control) would flip a site to the forced iframe. If your theme or your users’ sites sit anywhere near that line, now is a good time to check which side of it you’re actually on: it’s one is_file() call away.

Please consider helping!

Awake Freedom TV On Roku is Broken!  🙂

I could no longer maintain the costs on my own, so I moved the off of a dedicated server which was needed for the TV platform to work.  On top of that, I want to build an app Awake Freedom TV app, for mobile phones.  We need your help to first resurrect our TV channel, and then build the mobile app.   In order to do that, I need a minimum of 800/month on subscription payments.  Please help anyway you can with the form below.