Global style variations

Level: ,

Estimated reading time: 3 minutes

Last updated April 20, 2022, for Gutenberg version 13.0.

What are global style variations?

With global style variations, users can choose between predefined color palettes and block styles. A theme developer can add color, font family variations, and a dark mode. Or why not boxed and full-width layouts?
Style variations are available for block themes with Gutenberg version 12.5 or newer.

Users can select and preview the styles by going to WordPress Admin > Appearance > Editor (Beta) > Styles sidebar > Browse styles:

Hovering over the style variations shows the label.

How to add global style variations to a block theme

Global style variations are additional theme.json configuration files. The format, styles, and settings are the same as in theme.json.
When the user selects the variation, WordPress applies the style variation in addition to the default theme.json file.

In other words, you can completely override theme.json. But if all you want to change is the color palette, then that is all that you need to include. Any settings and styles that are not specifically overwritten are inherited from theme.json.

For WordPress to register the style variation, you need to place the JSON file inside a folder in your theme called styles. Example folder structure for the theme:

assets (dir)
patterns (dir)
styles (dir)
templates (dir)
parts (dir)

There are no limitations in naming the file except for the file extension, which needs to be .json. From Gutenberg version 13.0, you can add a title that will show as a label in the Site Editor.
If you do not include a title, the file name (without the extension) will show instead.

	"version": 2,
	"title": "Light",

Example use case & implementation tips

I used a style variation to add a light version to the advanced starter theme that I am using in the block theme generator. The background color in the dark (default) version is the foreground color in the light version.

View the code: Original. Variation.

I recommend that you back up the original theme.json file and make your changes in the theme.json in the root folder.
This will save you tons of time because you will not need to change and reset the global style variation in the Site Editor while you are testing.
Copy the updated file to the styles folder once you have finished, and then restore the original theme.json file.

Combining custom CSS and variations

When you add style variations to a block theme with custom CSS, you want to ensure that the CSS and the variations work well together.
WordPress applies the theme’s custom CSS after the style variation, and there is no way to identify which style variation the editor is using. In my case, I replaced some hard-coded CSS values with CSS custom properties in theme.json so that I could override the values using the variation.


Original pull request in the Gutenberg GitHub repository.