Discover in this tutorial the internal structure of the theme.json file and learn how you can customize it.
WordPress 5.8 introduced the theme.json file which is one of the key pieces on which the FSE (Full Site Editing) block themes are based.
The good thing is that the theme.json file can be used in classic themes so I invite you to get familiar with it as soon as possible.
That’s why I’m preparing a series of tutorials focused on how it works and how you can modify it to your liking.
Indeed, from this file you can customize many aspects of a WordPress theme:
- Color palette, gradients and douotones
- Fonts/Typography (families, size…)
- Site width
- Spacing
- Block styles
- Global style variations
- Management of template parts (FSE themes)
- Block templates management of(FSE themes)
- Define custom CSS properties
- And more.
Offering so many options (and with each WordPress update more are added) it can be a bit intimidating. In fact, if you open the theme.json file of any block theme, for example, Twenty Twenty-Two, you’re going to find more than 300 lines.
That’s why in this tutorial we’re going to go through the structure to familiarize you with it. Then you will feel more prepared to customize the settings you want or even add new ones.
Internal structure of the theme.json file
This would be the “skeleton” of a theme.json:
}
"version": 2,
"settings": {},
"styles": {}
}
That is, in addition to the version there are two main sections:
- version: currently version 2 (from WordPress 5.9 onwards)
- settings: where you define the block controls, color palettes, font size…
- styles: where you apply those colors, font sizes… to the website.
If you are going to use the file in a classic theme this will be enough. But if you are going to use it in an FSE theme, there are two sections that have been added more recently that may also be interesting to you. The structure would look like this:
}
"version": 2,
"settings": {},
"styles": {},
"customTemplates": {},
"templateParts": {}
}
- version: currently version 2 (from WordPress 5.9 onwards)
- settings: where you define the block controls, color palettes, font sizes…
- styles: where you apply those colors, font sizes… to the website.
- customTemplates: where you assign the block templates that can be modified from the template editor (FSE themes).
- templateParts: where you assign the template parts, such as headers or footers (FSE themes).
These would be the sections found in the first level of the structure. But within these are other sub-sections
As there are many (and continue to expand in each version of WordPress), I will highlight the most important when customizing a theme:
- version
- settings
- color
- palette
- gradients
- duotone
- layout
- spacing
- typography
- fontFamilies
- fontSizes
- color
- styles
- blocks
- color
- elements
- spacing
- typography
- customTemplates
- templateParts
As you can see the semantics used make it quite easy to understand what each setting is responsible for.
And you can surely intuit which settings you need to modify to configure the elements mentioned in the first list.
The settings and properties of the theme.json file are many and going through them all in this tutorial does not make sense, as we are going to dedicate specific tutorials for each section.
But I do think it is interesting to see how an “empty” theme.json file looks like so that you can visualize its settings and properties represented:
{
"version": "2",
"settings": {
"appearanceTools": true,
"border": {
"color": true,
"radius": true,
"style": true,
"width": true
},
"color": {
"text": true,
"background": true,
"link": true,
"custom": true,
"customDuotone": true,
"customGradient": true,
"defaultGradients": false,
"defaultPalette": false,
"duotone": [],
"gradients": [],
"palette": [
{
"color": "",
"slug": "",
"name": ""
}
]
},
"custom": {
"spacing": {
"small": "",
"medium": "",
"large": "",
"outer": ""
},
"typography": {
"dropCap": false,
"fontSize": {
"small": "",
"medium": "",
"large": ""
},
"lineHeight": {
"tiny": 1.15,
"small": 1.2,
"medium": 1.4,
"normal": 1.6
}
}
},
"layout": {
"contentSize": "",
"wideSize": ""
},
"spacing": {
"blockGap": null,
"margin": true,
"padding": true,
"units": [
"px",
"em",
"rem",
"vh",
"vw"
]
},
"typography": {
"customFontSize": true,
"dropCap": true,
"fontFamilies": [],
"fontSizes": [],
"fontStyle": true,
"fontWeight": true,
"letterSpacing": true,
"lineHeight": true,
"textDecoration": true,
"textTransform": true
}
},
"styles": {
"border": {
"color": "",
"radius": "",
"style": "",
"width": ""
},
"color": {
"background": "",
"gradient": "",
"text": ""
},
"filter": {
"duotone": ""
},
"spacing": {
"blockGap": "",
"margin": {
"top": "",
"right": "",
"bottom": "",
"left": ""
},
"padding": {
"top": "",
"right": "",
"bottom": "",
"left": ""
}
},
"typography": {
"fontFamily": "",
"fontSize": "",
"fontStyle": "",
"fontWeight": "",
"letterSpacing": "",
"lineHeight": "",
"textDecoration": "",
"textTransform": ""
},
"elements": {
"link": {
"border": {},
"color": {},
"spacing": {},
"typography": {}
},
"h1": {},
"h2": {},
"h3": {},
"h4": {},
"h5": {},
"h6": {}
}
},
"customTemplates": [],
"templateParts": [
{
"area": "footer",
"name": "footer",
"title": "Footer"
},
{
"area": "header",
"name": "header",
"title": "Header"
}
]
}
In this case, the values that would be added between quotes ""
and the arrays that would be added between the square brackets []
and braces {}
are missing.
You can also see that there are several settings that can be set to true
or false
.
Don’t worry because you don’t have to learn by heart either the structure or settings. In fact, in the next tutorial I show you a trick that will make your life much easier in this regard:
I hope that after this review you will find it easier to understand the contents of a theme.json file and above all that it will serve as a basis to apply the following tutorials where we will customize different sections.
Conclusions
Understanding the structure of the theme.json file is a must if you want to start taking advantage of it, both in classic and block themes (FSE).
Now that you know it a little better, in the next tutorials I will explain how to use it to customize WordPress themes.
If you have any question, please leave it in the comments. And if you want to give me a suggestion for future snippets, please send it through the contact form.
Benefits of being a subscriber. 🙂