An Introduction to WordPress Block Themes

The components that make up a typical WordPress theme haven’t changed much over the years. So much so that project co-founder Matt Mullenweg quipped that the old school Kubrick theme (released in 2005) still works with modern versions of the content management system.

Sure, theme developers have bolted on their own additions. We’ve seen everything from complex settings UIs to integrated page builders. But at their core, themes have maintained a consistent structure. That is, until the introduction of block themes.

Block themes are set to become the future of WordPress. They’ll change the way we build and maintain websites. In addition, they are more tightly integrated with the Gutenberg block editor than their “classic” counterparts.

Wondering what all the fuss is about? Today, we’ll fill you in on the basics of WordPress block themes. Along the way, we’ll explore how they compare and contrast to traditional themes. Let’s get started!

Why Block Themes?

For the first few years of its existence, the block editor has been primarily a means to style and build content. When combined with a classic theme, this meant that pages and posts could be crafted to your heart’s desire.

When it comes to making changes that impact the entire theme, the WordPress Customizer has remained the go-to resource. This tool provides access to design and layout settings that have been made available by the theme’s author. If it’s not in the Customizer, you’ll likely have to dig into code.

However, one of the key tenets of the block editor has been to create a more unified interface within the WordPress dashboard. We’ve already seen this happen with the Widgets screen moving to a block-based UI. The Customizer simply doesn’t fit this mold.

The introduction of Full Site Editing (FSE) is the next step in this process. It goes beyond just styling up our pages and posts. Now, every aspect of a theme’s design (header, footer, page templates, etc.) can be managed directly within WordPress.

Block themes serve as the gateway to this functionality. As such, they’re built exclusively with blocks in mind.

Changing a website header with the WordPress Site Editor.

The Inner Workings of a WordPress Block Theme

There aren’t a ton of similarities between classic and block themes. But both have a set of basic rules that guide their makeup. If you were to download a block theme and navigate its file structure, a few key contrasts may stand out.

Template Files Are HTML, Rather than PHP

In a classic theme, you’ll find template files with names such as index.php and header.php. Block themes do away with PHP and instead carry the .html file extension.

Inside, a template file contains a combination of HTML and block markup. For example, let’s take a look at this template from the official WordPress documentation:

<!-- wp:site-title /-->

<!-- wp:image {"sizeSlug":"large"}  -->
<figure class="wp-block-image size-large">
    <img  src="https://cldup.com/0BNcqkoMdq.jpg" alt="" />
</figure>
<!-- /wp:image -->
 
<!-- wp:group -->
<div class="wp-block-group">
    <!--  wp:post-title /-->
    <!--  wp:post-content /-->
</div>
<!-- /wp:group -->
 
<!-- wp:group -->
<div class="wp-block-group">
    <!-- wp:heading  -->
     <h2>Footer</h2>
    <!--  /wp:heading -->
</div>
<!-- /wp:group -->

Block markup looks an awful lot like HTML comments. But it includes syntax for calling specific blocks into the template. The WordPress Full Site Editing website has a handy reference that includes markup for each default block.

And if this type of code seems familiar, you may have seen something similar inside Gutenberg’s code editor view.

The Use of Folders

Classic themes are capable of storing templates within folders, but it’s not a necessity. Block themes require a couple of subfolders:

/parts
Contains reusable items such as the header, footer, and sidebar.

/templates
Houses templates for various types of content. Items like pages, post archives, and, singular posts are common examples. Note that their naming convention follows the WordPress template hierarchy – another similarity with classic themes.

One of the positive side effects of this arrangement is that themes will be better organized. Having a standardized folder structure means less time spent searching for a particular file.

Theme.json Styling

The theme.json file is used to assign default settings to the block editor. This means, among other things, that it’s possible to set default color palettes, typography, and spacing. Settings can be sitewide or applied to specific blocks.

Since theme.json will automatically generate the appropriate CSS based on its configuration, you may not need to fill up a theme’s style.css file quite so much. In that scenario, the stylesheet is used to define a few basics, while everything else relies on this newfangled file.

An example of WordPress block theme structure.

Creating and Editing Templates

WordPress has long provided the ability to edit a theme’s template files directly within the dashboard. This was often discouraged, as even a small coding error could render a website inaccessible. Not to mention the possibility of changes being overwritten when a theme is updated (thus, part of the reason for using a child theme). Some developers turn off the feature altogether to avoid even a remote chance of catastrophe.

But block themes are all about editing within the dashboard. Templates that are included with a theme can be tweaked via the block editor, and new custom templates can be created as well.

As you might expect, code is completely optional in this scenario. Everything can be edited via the new Site Editor (Appearance > Editor – WordPress 5.9 or above required) which replaces the legacy Customizer when a block theme is activated. And, just like pages or posts, the Site Editor uses the familiar block editor UI.

And that’s not all. Whatever changes you make within WordPress can be exported. This would enable you to use your customized block theme on multiple websites.

This lowers the barrier to entry for those who want to customize or even create themes. Now, a basic eye for design and a working knowledge of blocks can lead to a custom website.

A template listing inside the WordPress Full Site Editor.

Things to Keep in Mind

Before you dive in and switch all of your websites to use block themes, there are a few things you should know.

First and foremost, block themes are a nascent technology. Not all features have been finalized and some best practices need to be ironed out. Plus, we’re just starting to see how these themes work in a production environment. Expect several changes as things evolve.

If you build sites for clients and want to maintain some future flexibility, hybrid themes may be of interest. They allow for the use of FSE features while still maintaining the PHP structure of a classic theme. You can even retrofit an existing theme to use this functionality.

Finally, block themes do not spell the end for classic themes – at least not for the foreseeable future. With that, the transition to this new way of theming doesn’t have to be immediate. It’s OK, for example, to experiment with blocks in a local environment while still relying on your favorite classic themes in production.

An example from the Twenty Twenty Two theme.