To get started with my Full Site Editing block themes series I gave a little block theme introduction. Today I want to take a closer look at the theme.json file that has been around since WordPress 5.8. This small file changes the way we build WordPress themes tremendously. The theme.json file is the control center of block themes and will simplify the way WordPress themes are build.

At the moment the file is available in a first version and quite a few things are still in development. But I think it’s very important that we theme developers take a close look at the new developments now and participate as much as possible. This way we can learn more about the new block themes for Full Site Editing. We can take advantage of all the amazing new options we have building themes.

Why Block Themes need a theme.json file?

A JSON file (JSON stands for JavaScript Object Notation) is a file in an easy-to-read text format that contains important data for it’s project.

The theme.json file gives theme authors the option to define basic theme settings like the default theme widths, available font families, font sizes and color palettes.

Additionally, styles and color palettes can be specifically defined for individual blocks as well. Theme users can then customize these styles via the Global Styles in the Site Editor.

The big advantage here this is that theme users of block themes can now customize the styles for their website with more flexibility. Previously, themes offered such customization options via the Customizer. However, there was never a general system that all themes used. Instead each theme solved the customizer settings a bit differently. Customizer theme settings were not very user-friendly and the code for customizations via the Customizer were quite complex.

The new theme.json file in contrast feels like a much needed breath of fresh air for WordPress themes. The new options provide us with a consistent experience for theme developers and users.

The theme.json file structure

At the moment the theme.json file has three main parts: Settings, Styles and Custom Templates/Template Parts.

The theme.json file structure.


The Global Styles of a block theme are defined under Settings. Here you set the general color, dual tone and gradient palettes. The font families and font sizes are also defined in Settings as well as additional font options like text transforms, text decoration and the option for custom font sizes and custom line-heights.

Parts of the 2022 theme’s theme.json file (which is currently under development).

Another important setting is layout. Here you define the default width and wide width your theme should have.

"layout": {
"contentSize": "690px",
"wideSize": "1400px"

Spacing and Border setting options can also be enabled in the theme.json file.

"spacing": {
"blockGap": true,
"margin": true,
"padding": true,
"units": [
"border": {
"customColor": true,
"customRadius": true,
"customStyle": true,
"customWidth": true

Additionally, you can also create your own custom CSS variables in your theme.json file. We use this option to define color variables, a heading and body font variable and default line-heights in our Aino theme.

"custom": {
"color": {
"background-primary": "var(--wp--preset--color--background-primary)",
"background-secondary": "var(--wp--preset--color--background-secondary)",
"button-color-primary": "var(--wp--preset--color--button-color-primary)",
"button-color-secondary": "var(--wp--preset--color--button-color-secondary)",
"font-primary": "var(--wp--preset--color--font-primary)",
"font-secondary": "var(--wp--preset--color--font-secondary)",
"font-tertiary": "var(--wp--preset--color--font-tertiary)",
"primary": "var(--wp--preset--color--primary)",
"secondary": "var(--wp--preset--color--secondary)",
"star-rating": "var(--wp--preset--color--star-rating)"
"line-height": {
"body": 1.4,
"heading": 1.1
"body": {"typography": {
"fontFamily": "var(--wp--preset--font-family--arimo)"
"heading": {
"typography": {
"fontFamily": "var(--wp--preset--font-family--arimo)"

You can also define default settings for individual blocks, giving blocks their own color palette, for example.

This example shows a custom color palette for the Preformatted block.


In Styles you can determine which default values should be uses in your theme. This is helpful to set the theme’s default background color, default fonts and font styles.

In addition, you can define default styles of individual blocks. For example, you could set the font family and font weight of the Post Title block.

Custom Templates and Template Parts

In this section of the theme.json file the Page Templates and Template Parts of the theme are listed. Theme authors must specify all HTML files stored in the block-templates and block-template-parts folders.

"customTemplates": [
		"name": "blank",
		"title": "Blank",
		"postTypes": [
		"name": "page-home",
		"title": "Homepage",
		"postTypes": [
"templateParts": [
		"name": "header",
		"title": "Header",
		"area": "header"
		"name": "footer",
		"title": "Footer",
		"area": "footer"

The files must have a name and a title and it must be defined in which area the files should be available. Theme users can then customize these files via the new Full Site Editing Site Editor.

Theme.json in classic themes

The new theme.json file settings replace many of the settings previously defined via add__theme__support in the functions.php file of a theme.

By the way, even classic themes can use a theme.json file and thus clean up their functions.php. This makes it possible to gradually transform your theme into a block theme step by step.

Questions and feedback

There is so much new things happening in WordPress development right now and it can be difficult to keep up with everything. Especially theme developers are under a bit of pressure right now to prepare for new Full Site Editing features coming in WordPress 5.9. Therefore I want to make sure I share as much as possible from what we’ve learned so far.

Please let me know if you have any questions or ideas for new Full Site Editing and block theme post topics.

Did you have a look at block themes or used a theme.json file in your own theme? If so, how was your experience and what did you like or dislike? What advantages or difficulties do you see for the development of WordPress themes in the future? Please write me a comment or contact me via Twitter. I would love to hear from you.

Helpful resources for further reading: