In this lunchtime #WPQuickies, I explain how the global settings and styles file theme.json works.
WordPress 5.8 shipped with theme.json, a new way of being able to set global settings and styles for your themes and for block editor blocks.
Theme.json is part of a suite of full site editing tools being developed for WordPress.
What is theme.json?
As the WordPress editor blocks increase in number and complexity, the open-source project committers have been trying to find a way of being able to define a standard way of configuring all the settings and styles.
The theme.json file is the first iteration of this global configuration feature.
WordPress comes with its own default settings and styles for core editor blocks like paragraphs, heading and images.
Themes also come with their own blocks, settings and styles that are applied in the block editor and also on the front-end of the website.
It can be pretty daunting to try and consistently apply a company brand to all these blocks.
The theme.json file allows you to apply settings and styles to block elements using the JSON format.
Note: the theme.json file is very much a “work-in-progress”, so expect changes to the format in future versions of WordPress.
Please refer to the official documentation for the most recent version and updates to the theme.json file.
Global Settings & Styles (theme.json)
What Is JSON and What Is It Used For?
JavaScript Object Notation (JSON) format is used for serializing and transmitting structured data over the internet.
It is primarily used to transmit data between a server and web applications.
The format has gained popularity because it is understood by computers and is also easily readable by humans.
Who Should Use theme.json?
Theme developers and designers will benefit from using the theme.json file, especially for client branding purposes.
Being able to set the style for headings H1 to H6, paragraphs and other branded elements, and to apply brand colours in the editor will save a lot of time.
Where Can I Find theme.json?
The theme.json file should reside in the root of your active theme directory.
For example, if you are using the TwentyTwenty theme on a typical WordPress installation, the theme.json file path will be /wp-content/themes/twentytwenty/theme.json.
If you are using a child theme, your theme.json file should reside in the root directory of that child theme, for example,/wp-content/mytheme/theme.json.
How theme.json Works
When the WordPress core app loads in, it applies its own settings and style that it comes bundled with.
When the active theme is loaded in, the theme will apply its own settings and styles which can override those from WordPress core.
When a site admin adds additional CSS in the customiser or from a child theme, those settings and styles override those from the active theme.
This is how cascading style sheets (CSS) and block settings work.
Managing Styles
By using the theme.json file to set style properties in a structured way, the Block Editor can “manage” the CSS that comes from different origins (user, theme, and core CSS).
For example, if a theme and a user set the font size for paragraphs, we only enqueue the style coming from the user and not the theme’s.
The advantage of this approach is that it reduces the amount of loaded CSS which decreases specificity wars where users have to target an element using a large number of specific classes or worse, use the !important override.
Example theme.json File
Here’s a quick example of what a small theme.json file might look like.
{
"version": 1,
"settings": {
"color": {
"palette": [
{
"name": "Pumpkin",
"slug": "pumpkin",
"color": "#F27D20"
},
{
"name": "Hokey Pokey",
"slug": "hokey-pokey",
"color": "#FABE34"
}
]
}
}
}
The current version of the theme.json file needs to be 1, otherwise, it will not be recognised and loaded in by WordPress.
This example theme.json file applies a colour palette to the colour settings used by core editor blocks.
Here are the default GeneratePress block colour settings.
After applying the above theme.json file, the colour pallet now looks like this.
Specific Block Settings
Where the above example set the colour settings for all core blocks, this example disables the custom colour feature globally but then re-enables that feature just for the core paragraph block.
{
"version": 1,
"settings": {
"color": {
"custom": false
},
"blocks": {
"core/paragraph": {
"color": {
"custom": true
}
}
}
}
}
The theme.json file allows you to apply global style settings as well as those for a specific block.
Custom Block Templates
If you are using custom block templates, these can be specified in the theme.json file and applied to whatever post types are needed.
{
"version": 1,
"customTemplates": [
{
"name": "my-custom-template",
"title": "The template title",
"postTypes": [
"page",
"post",
"my-cpt"
]
}
]
}
The same applies to block template parts. See the developer documentation for more information.
What Else Can theme.json Configure?
At the moment the theme.json file can support a version, block settings, styles (including custom non-block styles), custom templates and template parts.
Here’s the top-level structure for the theme.json file.
{
"version": 1,
"settings": {},
"styles": {},
"customTemplates": {},
"templateParts": {}
}
Here’s an example of setting global styles using the theme.json file.
{
"version": 1,
"styles": {
"border": {
"color": "value",
"radius": "value",
"style": "value",
"width": "value"
},
"color": {
"background": "value",
"gradient": "value",
"text": "value"
}
}
}
Styles found at the top level of the JSON file will be enqueued using the body selector.
What about Customiser CSS?
If you use the “Additional CSS” section of the Customiser to add CSS to your site, the customiser CSS will override theme.json style settings.
So don’t worry if a future theme comes bundled with a theme.json file for settings and branding.
You can either edit the JSON file or override styles using additional CSS within the customiser.
Summary
The theme.json file is a step in the right direction towards WordPress global style and settings.
It’s likely to change and broaden its scope in future WordPress versions.
Definitely, one to keep an eye on.
#WPQuickies
Join me every Thursday at 1 pm Sydney time for some more WPQuickies – WordPress tips and tricks in thirty minutes or less.
Broadcasting live on YouTube and Facebook.
Suggest a #WPQuickies Topic
If you have a WordPress topic you’d like to see explained in 30 mins or under, fill out the form below.
https://forms.gle/mMWCNd3L2cyDFBA57
Watch Previous WPQuickies
