The term “block theme” appears frequently in WordPress discussions. However, the technical definition from a code perspective remains unclear to many developers. Understanding what WordPress core actually checks when determining block theme status has become critical, especially with upcoming changes in WordPress 7.1.

The Block Theme Classification Crisis

Research into WordPress 7.1’s post editor changes revealed a significant implementation detail. Core might force the iframe editor only for block themes. Classic themes using blocks with apiVersion 2 or lower would maintain current 7.0 behavior. This distinction makes the exact definition of “block theme” crucial for developers and site owners.

The classification affects how your theme interacts with the editor. Additionally, it determines which editing experience your users receive. Therefore, knowing where your theme falls on this spectrum matters more than ever.

What wp_is_block_theme() Actually Tests

The public API function wp_is_block_theme() provides the official check. This function simply queries the active theme through wp_get_theme()->is_block_theme(). The implementation, however, reveals something surprising about WordPress’s classification logic.

The WP_Theme::is_block_theme() method performs a straightforward file-existence check. WordPress looks for an index.html file in two specific locations. The function searches /templates/index.html first, then checks the legacy /block-templates/index.html path. If either file exists and is readable, WordPress considers the theme a block theme.

This approach has significant implications. WordPress ignores every other theme feature when making this determination. The check focuses exclusively on whether a specific template file exists in the filesystem.

What Doesn’t Make You a Block Theme

Several features might seem like they would classify a theme as a block theme. However, WordPress core ignores all of these elements. A theme.json file does not trigger block theme status. Similarly, patterns, block template parts, and add_theme_support(‘block-templates’) have no effect on the classification.

A theme can adopt every hybrid feature available and still register as classic. The test only looks for the top-level index.html template file. This narrow focus surprises many developers who expect a more comprehensive evaluation.

Child Themes and Inheritance

Child themes automatically inherit their parent’s block theme status. The get_file_path() function looks in the child theme directory first. Then it falls back to the parent theme if necessary. This means a child theme of a block theme remains a block theme even without its own templates.

This inheritance happens regardless of what the child theme contains. Developers cannot override a parent block theme to create a classic child. The parent’s templates/index.html file determines the classification for the entire theme hierarchy.

Minimum File Requirements

A minimal viable block theme requires only two files. The theme needs a style.css file with a standard theme header. Additionally, it must include templates/index.html. This single template file acts as the decider for block theme classification.

WordPress considers a theme valid with specific file combinations. A theme needs style.css plus either index.php or templates/index.html. For block themes, index.php, functions.php, and even theme.json are optional files. The templates/index.html file alone determines block theme status.

Staying Classic

Maintaining classic theme status requires meeting two conditions. First, the theme must not contain templates/index.html or block-templates/index.html. Other block templates do not affect the classification. A theme with templates/single.html but no templates/index.html still tests as classic.

Second, the theme cannot have a block-theme parent. The check examines the entire parent chain. To remain classic, every theme in the hierarchy must lack the index.html template file.

Everything else remains flexible. Themes can use theme.json, patterns, and add_theme_support(‘block-template-parts’). Custom templates registered from plugins also do not flip the classification switch. Only the presence of templates/index.html matters.

Real-World Theme Classifications

Popular WordPress themes demonstrate this classification system in practice. Twenty Twenty-One and all earlier default themes test as classic. Meanwhile, Twenty Twenty-Two and subsequent default themes register as block themes. This division marks a clear turning point in WordPress theme development.

Major third-party themes show interesting patterns. Astra, Kadence, Blocksy, Botiga, Sydney, and Hello Elementor all ship theme.json files. Nevertheless, they test as classic themes because they lack templates/index.html. GeneratePress, Neve, OceanWP, and Storefront follow the same pattern.

Six themes with theme.json still classify as classic. This demonstrates that WordPress never consults theme.json for classification purposes. The presence of this marquee block feature does not influence the core check.

Common Classification Gotchas

Twenty Twenty and OceanWP illustrate a common misconception. Both themes ship a templates/ directory yet remain classic. Their templates folders contain PHP page templates like template-cover.php and landing.php. The check specifically requires templates/index.html, so the mere presence of a templates folder means nothing.

How the Editor Reads Block Theme Status

The block-theme flag appears in two places on the JavaScript side. Understanding these locations helps when investigating editor behavior or debugging theme-related issues. The flag surfaces through different APIs for different purposes.

First, it appears as an editor setting. The get_block_editor_settings() function sets ‘__unstableIsBlockBasedTheme’ using wp_is_block_theme(). This provides the editor with direct access to the theme classification during initialization.

Second, the REST themes endpoint exposes the flag. The class-wp-rest-themes-controller.php file sets ‘is_block_theme’ from the theme object. The @wordpress/core-data package retrieves this information through the REST API. This allows JavaScript code to query theme status asynchronously.

The Single File That Changes Everything

The entire concept of “block theme” reduces to one file check. WordPress asks whether templates/index.html exists. The answer determines the theme classification completely. No other files, features, or declarations factor into this decision.

This simplicity carries significant weight for WordPress 7.1. If the release draws the iframe editor line at wp_is_block_theme(), themes near the boundary face consequences. A hybrid theme adopting everything except block templates would maintain classic editor behavior. However, adding a single templates/index.html file would flip the site to forced iframe mode.

The flip can happen accidentally or through parent theme updates you do not control. Theme developers and site owners should verify their current classification. The check comes down to one is_file() call. Testing takes seconds, but the results determine your editing experience in WordPress 7.1 and beyond.

Now is the time to check which side of the line your theme occupies. Understanding this classification helps you prepare for upcoming WordPress changes. The distinction between block and classic themes will only grow more important as WordPress continues evolving its editor experience.

Original Source: gutenbergtimes.com