Theme style variations

A theme style variation is an optional design for a block theme. You can use style variations to change the look of the website without needing to switch themes. Style variations are like a layer on top of the existing blocks and templates and can change one or many styles on the website. It can use different font families and font sizes, new colors, and spacing.

Right now, variations are unique to the active theme. In the future, we might be able to copy, import and export them. has published a detailed beginner’s article on how to use style variations. This lesson, on the other hand, will focus on how you can create your own.

Level: ,

Estimated reading time: 5 minutes

Last updated

How to select and preview a style variation

You can preview style variations in the WordPress Site Editor. Open the Styles sidebar by clicking on the half-black, half-white circle icon, and then select “Browse styles.”
In the sidebar, you will find a small preview of the font family and part of the color palette.
In the example video, I have named the variations “Light” and “Blue”:

When you have selected a variation, don’t forget to save the changes.

How to add your own style variation

In this lesson, I want to show you how to add your own variation without coding using the Create Block Theme plugin.

First, you must choose which theme you want to add the variation to. In most cases, you want to add the variation to your own custom theme or child theme. Because if you download a theme update from another theme developer, WordPress replaces all the files, including your variation file.

Make sure that the theme you selected is the active theme on your WordPress installation. Next, please download Create Block Theme from the plugin directory and activate it.

Open the plugin options page under Appearance > Create Block Theme:

The Create Block Theme options page with the "Create a style variation" option selected.

The way the plugin works is that when you select the option “Create a style variation” and finalize it by clicking on the “Generate” button, the plugin copies all the settings from the Styles sidebar. Both the site-wide styles and the block-specific styles. It then creates a new style variation file in the theme folder.

Back up your current style

I strongly recommend creating a style variation that will function as a “backup” of any style changes you have made so far. With style changes, I only mean changes that you have made in the Styles sidebar: Not changes made to blocks in your content or customized templates.

After you click on the “Generate” button at the bottom of the options page, you will see a notification that your style variation has been saved.

Create your new style variation

Open the Site Editor from Appearance > Editor and open the Styles Sidebar.

Explore the style changes you want to make. You can update the theme color palette and change the body background color, text, link, and button colors. You can make the default content wider or narrower, and so on.
Style common blocks like headings, post titles, and images: you can even add a default duotone to images in your style variation.

Remember that if you add or remove blocks, WordPress does not save those changes as part of the style variation but as template customizations stored in the database.

The trick to successfully updating the color palette is to not change the names of existing colors! If you have a body background color called “base,” which is white by default, it can be light grey in variation 1 and dark blue in variation 2: But it needs to be called “base” in all 3 variations. Otherwise, the color will not be applied correctly.

Here is another advanced tip for you: You can add accent colors that are unique to a style variation. Not all style variation needs to use the same amount of colors; they can add extra colors to the palette.
For example, in style variation 1, you decide not to change the color of the site title block; you will just use the default. But in style variation 2, you want to use a new color that is not used anywhere else on the website. So you add a new color, and you assign that as the text and link color for the site title.
If you switch to variation 1, that new color will not be used because it does not exist in the palette.

Test and preview your styles

I recommend that you preview your changes using several different pages: Archive, custom templates, single posts, 404, and so on, not only your front page: Just to make sure you did not miss any places where you might need to update a color.
Make sure that all your content and links are still readable so that there are no areas where the background and text use the same color. 😊

Save the variation file in the theme

As the final step, save your changes in the Site Editor, and return to the plugin’s options page under the Appearance menu > Create Block Theme. Select the option “Create a style variation” again and save your new variation.

Your variations will now show as options under Styles > Browse Styles.

How to delete style variations

I want you to know that WordPress has no user interface for deleting style variations. So if you ever need to remove a variation, you need to delete its file. Each style variation has its own file inside a folder in the theme called styles. If you named your style variation “Variation 1”, the file you need to delete is styles/variation-1.json.


If you are trying to find a style variation in the theme but you can not find a matching file name, you can open the .json file in any text editor and look at the top of the file. The file should contain the title of the variation, like in this example from the theme Twenty Twenty-Three:

This variation is called “Whisper” in the Site Editor interface:

	"$schema": "",
	"version": 2,
	"title": "Whisper",

Style variations in child themes

If you have created a child theme of a t theme with style variations, the child theme will inherit all the style variations from the parent theme.
If you need to remove a parent theme style variation, you can place a blank file with the same file name inside the styles folder of the child theme.


Developer guide to style variations