Universal Themes

Since our last post about Universal Themes we have fleshed out this idea and are using it to build all our themes.

The Problem

WordPress is introducing the Full Site Editor and with it new ways to build themes.  These themes are called “Block” themes and integrate deeply with Gutenberg Blocks. These types of themes require the use of the new (and still in development) Full Site Editor. 

The Site Editor is still being built, and block themes are in a nascent stage; they don’t yet offer the full gamut of features that will be available in the future. Block themes also require a very recent version of WordPress. How can we build themes which work with the classic dashboard to today and will continue to work with the Site Editor when it is more fully featured? This is the problem Universal themes are seeking to solve.

What is a Universal Theme?

Universal themes are an attempt to bridge the gap between the classic themes and block themes, by adding some layers to a block theme to make it work.

A Universal theme is a block theme that can use the Full Site Editor but can also be configured in a more classic way.  That means that you can use classic WordPress tools, like the Customizer, Menus and Widgets dashboards as well as the Site Editor.


Block themes load templates from the block-templates directory. However classic themes load them from the root. To ensure that we don’t end up duplicating code and that users can move between the Classic Dashboard and the Site Editor, we use the function gutenberg_block_template_part inside our classic templates. For example header.php:

<header class="wp-block-template-part">
	<?php echo gutenberg_block_template_part( 'header' ); ?>


Because block themes use html templates, its not possible to translate any copy inside them. In most cases we can avoid putting copy inside our templates, but there are some cases where it is impossible, for example the 404 page.

In these cases we are simply providing a classic template instead of a block template so that the strings can be translated. We can avoid any issues of code duplication by using the approach described above for templates. Here’s the 404.php from Blockbase:

 * The template for displaying 404 pages (not found)
 * @package Blockbase
 * @since 1.1.1
	<main class="container-404">
		<h1 class="has-text-align-center has-medium-font-size"><?php _e( 'Oops! That page can&rsquo;t be found.', 'blockbase' ); ?></h1>

		<p><?php _e( 'It looks like nothing was found at this location. Maybe try a search?', 'blockbase' ); ?></p>

		<?php echo do_blocks('<!-- wp:search {"label":""} /-->'); ?>

Fonts & Colors

Global Styles allows themes to customize their font and color options via theme.json. This gives universal themes a way to modify the fonts and colors in a theme, by modifying theme.json. In Blockbase we have attached some hooks to the font and color controls in the Customizer so that when you modify them the changes are made in theme.json. This gives us a single source of truth for these settings.


We have created a universal theme called Blockbase, which can be used as a parent theme; any child themes created with Blockbase will automatically be universal themes. You can learn more about Blockbase at blockbasetheme.com.


Universal themes are a temporary measure. As the Site Editor continues to improve and more features are added, the need for universal themes will diminish. These wrappers will be made obsolete and in time universal themes will become block themes.

Author: Ben Dwyer

I make things. I particularly like to make music. Music is meant to be fun, that's why it's 'played'.

12 thoughts on “Universal Themes”

  1. How can I test it? If Gutenberg plugin is disabled, the `gutenberg_block_template_part` function is missing and if is enabled, the FSE is used. Thanks

    1. Hi Patrick. You will need to be running WordPress 5.8 for Blockbase to work correctly. If you run the Gutenberg plugin then you will have access to the Site Editor, but you will also be able to customize the theme using the Customizer and Menus screen in the classic Dashboard.

      1. I have WordPress 5.8 without Gutenberg and Blockbase not working. `Uncaught Error: Call to undefined function gutenberg_block_template_part()`.

  2. This thing has swallowed my comment like 4 times. Typing it out again. Remind me to figure out a better writing workflow than writing in a web browser (also an issue with gutenberg and autosave weirdness. I digress).

    Sigh. 4 times.

    Typing it the 5th time.

    Sorry about the noob questions.
    Right now this box is RED btw. Is it going to reject my post again with no message? RED means error, correct?
    Is there a rejected word in my message.
    Ok, how do I contact anyone about blockbase in a different medium. Should I use wordpress.org or github issues? unclear where to even ask this question.

    1. Comment went through! The red does not mean error. I have no idea why my other messages hung.
      Ok – thank you for the advancements in blockbase, btw. Very exciting stuff.
      Does one have to download the entire Automattic theme repository to use this version of blockbase to create the child theme? I checked on the blockbase page itself and there was no way to download or clone it, so I did clone the entire thing. Maybe this is intentional but just curious.
      So then I symlink’ed blockbase into my themes folder. Is this correct? I assumed so, so then I can continue to update this version of blockbase and keep it up to date with the Automattic github repository.
      I then tried creating the child theme from the synlink’ed version, just to see…it threw an error at the end, but the child theme was successfully created back in the Automattic folder.
      So do I symlink this child theme back into my themes folder?
      I assume so. But do these two need to be kept together now? Is the github version of blockbase going to be “ahead” of the wordpress.org version as far as merging theme.json with a child theme goes?
      I have not looked at the release version yet side by side, and wish I was like 40 minutes ago before typing this all out again lol.
      From here, not sure how to get the child theme into MY github, considering it’s in the Automattic folder which I know I will be updating.
      I’m a noob solo git guy and the giant Automattic folder part of this, I guess, is the intimidating / confusing part.

      1. On a positive note, once I installed chokidar-cli and one other thing (manually), no issues merging the child and blockbase theme.json etc.
        Very happy with how this is going to work! I just am unsure of the workflow as a solo git noob guy.

      2. Right now, you will need to clone the whole repo in order to get Blockbase. We hope to improve this workflow in the future. You might want to copy just the Blockbase directory into your WordPress installation.

        If you are creating your own child theme, it’s not necessary for your new theme to live in the Automattic themes repo – you can copy the files to wherever you need them, and as long as your WordPress installation can see them they will work.

Comments are closed.