Universal Themes: Customization

Making Global Styles and the Customizer work together

In the last post we shared the idea of a “universal” theme. This post looks at how we can use classic WordPress tools (in this case the Customizer) to customize a block theme, while saving these changes in Global Styles – making a universal theme!

Global Styles Everywhere

Block themes use a theme.json file to define many aspects of the theme, e.g. color palettes and typography. Gutenberg provides a tool to edit these settings (called Global Styles). When a user changes these values in the Global Styles UI, the changes are not saved back into the theme.json file but instead are saved to a Custom Post Type (CPT) in WordPress. Because this CPT can be modified using WordPress APIs, this gives us the power to make changes to Global Styles without relying on the interface in Gutenberg.

This simple idea is the basis for the color and typography customization options we have added to our universal theme Blockbase. The rest is just implementation details…

Implementation details!

When the Customizer loads, we create two new sections:

  1. Colors
  2. Fonts
		'capability'  => 'edit_theme_options',
		'description' => sprintf( __( 'Color Customization for %1$s', 'blockbase' ), $theme->name ),
		'title'       => __( 'Colors', 'blockbase' ),
		'capability'  => 'edit_theme_options',
		'description' => sprintf( __( 'Font Customization for %1$s', 'blockbase' ), $theme->name ),
		'title'       => __( 'Fonts', 'blockbase' ),

In each of these sections we create new settings and controls – each setting and control relates to a color/font option in Global Styles. We read the content of the theme.json file and use this to populate the settings in the Customizer. There is a helpful function in Gutenberg which merges together the theme.json settings with any user settings:


We read in an array of color palettes from the theme.json file and display these inside the “Colors” section:


One of the powers of Global Styles is that it relies on CSS variables. This makes it very easy for us to update the Customizer preview when the controls are changed. Some simple javascript injects new values for these CSS variables into the page, meaning that the preview updates instantly.

First we bind a listener to the control:

// For each of the palette items add a listener
userColorPalette.forEach( ( paletteItem ) => {
	const settingName = userColorSectionKey + paletteItem.slug;
	wp.customize( settingName, ( value ) => {
		value.bind( ( newValue ) => {
			paletteItem.color = newValue;
			blockBaseUpdateColorsPreview( userColorPalette );
		} );
	} );
} );

This updates the global variable userColorPalette, which we then use to create our CSS variables:

function blockBaseUpdateColorsPreview( palette ) {
	// build the CSS variables to inject
	let innerHTML = ':root,body{';
	palette.forEach( ( paletteItem ) => {
		innerHTML += `--wp--preset--color--${ paletteItem.slug }:${ paletteItem.color };`;
	} );
	innerHTML += ';}';

	// inject them into the body
	const styleElement = document.getElementById(
	styleElement.innerHTML = innerHTML;


Customizer settings are usually saved in a site option or a theme mod. Since we are building a universal theme, we need to save these changes into Global Styles so that they are reflected in the Site Editor. The easiest way we found to achieve this was to hook into the customize_save_after action, read the settings from the controls, and then update the Global Styles CPT with the new settings. This code is used to get and read the CPT:

get_post( $user_custom_post_type_id );
json_decode( $user_theme_json_post->post_content );

Once you have the CPT in JSON form it’s simply a case of adding the new settings to it, and saving them back into the CPT:

$user_theme_json_post_content->settings->color->palette = $this->user_color_palette;

wp_update_post( json_encode( $user_theme_json_post_content ) );

Color Palettes

Color palettes are simply combination of color settings. When a user selects a palette we simply change all of the associated colors at once. This can be done with the Javascript API:

wp.customize.control( userColorSectionKey ).setting.set( color );

How can I use this?

The code above is just pseudo code, to explain the concepts. For a fully working example see Blockbase freely available in our free themes repository. This code has a GPL license and can therefore be copied and distributed freely.

However, if you are interested in building a universal theme I would encourage you to use Blockbase as a parent theme. This will mean you get all future improvements to your theme for free!


The Customizer gets a bad rap, and it’s true that it is clunky when compared to the direct manipulation that is possible with Gutenberg. Nevertheless, building these kinds of tools to update Global Styles without the framework of the Customizer would have been much more involved. There is some satisfaction in being able to take advantage of all the hard work that has gone into the Customizer in its final years!

Universal themes: Some ideas

With the Full Site Editing project well underway, theme developers need to be thinking about what the future holds for themes. 

Why block themes?

To take advantage of the Site Editor, themes need to be built out of blocks – this is why we need block themes. Block themes are an entirely new way of creating themes. Classic themes bundle all of the code needed to control the presentation and functionality of the site, with the theme itself. This often means that themes contain extra code to add features (e.g. a slideshow) as well CSS to control the layout.

With block themes, much of the theme’s functionality and presentation is provided by Gutenberg. This means that themes have a shared set of features and style rules, which brings several benefits for users:

  1. The user experience for customising themes is more consistent.
  2. When users switch themes, they won’t lose features, as Gutenberg provides the same features to all themes.
  3. Users can mix and match aspects of different themes – e.g. the header of one theme with the footer of another.

There are also some benefits for developers:

  1. Less code is needed to build a highly functioning theme.
  2. Features that are used by many themes are now provided by the community, so that everyone benefits from the work done to maintain and improve them.

Can I use block themes today?

Block themes are the future and they will provide users great tools when Full Site Editing launches. For now, only those who are running the latest Gutenberg plugin and are willing to use experimental features like the Site Editor are able to use block themes.

Although the Site Editor is not yet ready, many aspects Full Site Editing will be available in WordPress 5.8. There is an opportunity to start building some form of block themes before Site Editor is ready.

Two editing modes

Full Site Editing brings a new editing mode for themes. For the sake of this article we’ll call the current editing mode, “classic” (Site Editor disabled) and the Full Site Editing mode, “FSE” mode (Site Editor enabled).

Users with classic themes will (probably) need to switch themes if they want to start using the Full Site Editing features. However if we can build block themes in a way that works in “classic” mode, then users will be able to take advantage of Full Site Editing once the tools are available. We have been calling themes like this “universal” themes.

Universal themes

The vision for universal themes is that a user could create a site using WordPress without the Site Editor enabled. Then, when the Site Editor is more mature, users could switch to using that, with all the extra tools that Full Site Editing will bring. 

A universal theme would work in both editing modes.  A user should be able to build a site in classic mode and switch to FSE mode when the Site Editor is more mature or when they are ready to try all the extra tools that Full Site Editing will bring. Changes to a theme in classic mode should be reflected when I enable the Site Editor.

Side note: It is not expected that users would toggle between these two modes. The plan will be for everyone to migrate to the Site Editor at some point. The intention of universal themes is to allow people to easily migrate from classic to FSE, not to encourage switching between them.


We that know that the Site Editor is coming. Building themes in this way will allow users to transition from classic themes to block themes when they are ready without requiring them to switch themes.

To achieve this we need to consider several aspects of themes:


In classic themes, templates live in the root directory and, by convention, `template-parts`. In block themes they live in `block-templates` and, by convention, `block-template-parts`. We could build templates for both classic and block themes and put them in the respective directories but the problem with this approach is that if users make changes to their templates when in classic mode they will not be reflected if they switch to the Site Editor.

To use the same templates when in classic and FSE mode we can put our templates in the `block-template-parts` directory. We can include them in our block templates in our template file like this:


<!-- wp:template-part {"slug":"page"} -->

For classic templates we can include the same file using `gutenberg_block_template_part`, which will execute `do_blocks` on this template:


echo gutenberg_block_template_part( 'page' );

This approach means that users can switch from classic to FSE mode without losing their changes.

Classic themes use `wp_nav_menu` to render theme navigation elements, which can be customised in the Dashboard, or in the Customizer. On the other hand, Block themes rely on the Navigation block to display their navigation. A recent change to the Navigation block means that we can connect these interfaces together:

By passing the navigation block an `__unstableLocation` attribute with the location of the classic menu, we can display classic menus inside the Navigation block:

<!-- wp:navigation {"__unstableLocation":"primary"} --><!-- /wp:navigation -->

This allows us to edit menus in the Customizer and the Dashboard when in classic mode, and in the Navigation block when in FSE mode.

Sidenote: A short-coming of this approach is that once the navigation has been edited in FSE mode, it will not be possible to edit it in classic mode.


In classic mode, the Customizer is the main tool for editing theme settings. Aside from Menus (see above), by default the Customizer allows users to edit Site Identity and Homepage Settings. These are WordPress settings that are editable elsewhere in the Dashboard, and are also available to block themes. The exception to this is “Additional CSS” which is not editable when the Site Editor is enabled. The hope is that the Site Editor will allow users to edit their site directly so that they won’t need to use additional CSS.

Often themes add more customisation options – for example colors and fonts. Global Styles offers some of the same customisations. Using the Global Styles API it is possible to make changes to Global Styles in the Customizer. This would allow users to customise their site using both the Customizer and Global Styles. We’ve been playing with this idea in this PR: Quadrat: Add color customization.

Opting in and out of the Site Editor

One unresolved challenge for universal themes is how to opt-in users to the Site Editor. At present the Site Editor is enabled for all block themes, which includes universal themes (if your theme has a file in the location `block-templates/index.html` it will be treated as block theme).

To be able to launch universal themes before the Site Editor is ready, we will need a mechanism to temporarily disable it. There is more discussion on this issue.

What’s next?

At the moment universal themes are just an idea; there are still many unresolved questions about how we could achieve this vision. For an example of a theme that tries to take a universal approach see Quadrat.

Look out for more posts about this idea as we keep experimenting with it.

Content Options in Jetpack 4.5

Now available through Jetpack, Content Options let users make small visual changes, like showing or hiding the author, date, featured images, and more.

Last August, we introduced a new WordPress.com Customizer panel called Content Options, which gives users an easy way to make small visual modifications across their sites – no custom CSS needed.

Content Options supports four main features: Blog Display, Author Bio, Post Details, and Featured Images.

Content Options are now available to self-hosted WordPress sites with the latest version of Jetpack (4.5). Theme developers can add support for Content Options by following the Jetpack guide.

Let’s look at the main features of Content Options in more detail.

Blog Display

Users can choose between displaying the full content of each post or an excerpt on the blog and category, tag, and date archive pages, as well as search results.

Full post blog display option in Shoreditch
Full post blog display option in Shoreditch

Post excerpt blog display option in Shoreditch
Post excerpt blog display option in Shoreditch

Default Blog Display

If a theme displays either an excerpt or the full post depending on the post’s post format, theme developers can add a “Default” blog display option to let the theme keep its default blog display settings. For example, by default a theme might always displays posts with the Quote post format as the full post, so a quote is never truncated, while other post formats like Standard might be always displayed as an excerpt.

Default blog display option in Button
Default blog display option in Button

Author Bio

On the single post view, users can opt to display the name and bio of the post’s author. This information comes directly from the author’s profile at Users  Your Profile, and their Gravatar image.

Author Bio displayed on single post in Shoreditch
Author bio displayed on single post in Shoreditch

Post Details

The post details section allows users to show or hide the post date, categories, tags, or the post author’s name.

Post Details displayed in Penscratch
Post details displayed in Penscratch

Post Details hidden in Penscratch
Post details hidden in Penscratch

Users can choose whether to display featured images on single posts and pages. They can also opt whether to display featured images on blog and archive pages, which include category, tag, and date archives as well as search-results pages.

Featured Images displayed in Sela
Featured images displayed in Sela

WordPress.com users have loved the flexibility Content Options gives them. We’re very pleased that self-hosted sites can now benefit as well!

Validation and Sanitization in the Customizer

At Automattic, we exclusively use the Customizer for theme options instead of theme option pages. We believe that themes should only alter the display of content and should not add any additional functionality that would be better suited for a plugin. Since all options are presentation centered, they should all be controllable by the Customizer.

Continue reading “Validation and Sanitization in the Customizer”