Making custom stylistic changes to your WordPress site generally means editing multiple files manually. Plus, if you switch themes, you’ll have to reconfigure all these settings from scratch. This can be a time-consuming process.
Fortunately, when WordPress launched version 5.8, it introduced a new theme.json file. This is a dedicated space for styling the block editor (and individual blocks) on the front and back end. As a result, it’s much easier to manage styles for your website.
In this post, we’ll take a closer look at the theme.json file. Then, we’ll run through some key considerations before we show you how to edit your theme.json file.
What is theme.json in WordPress?
The theme.json file is a mechanism that enables you to configure the Block Editor with greater control. It’s useful for making site-wide stylistic changes, since you can assign default styles to all (or some) of your blocks.
Essentially, theme.json is a solution that enhances the capabilities of the Block Editor API. For instance, with theme.json, you’ll gain the ability to control the editor programmatically. Plus, you can integrate a block style system. This facilitates how you manage user, theme, and core preferences.
The theme.json file was introduced at the same time as the Site Editor. In conjunction, theme.json is one of the first major steps to managing styles for future WordPress releases. It’s a great way to gain more control over your theme (and site) so that you can make changes to your menus, headers, and footers.
In short, the Site Editor enables you to make tons of global stylistic changes while theme.json is the mechanism that lets you configure custom options for your blocks.
For example, you can redefine the settings of the Block Editor to hide or show customization options for certain users. Additionally, you can define default colors and font sizes for your blocks while configuring a new width or alignment for the editor.
Where is the theme.json file located?
You can find your theme.json file inside the root of your theme directory. If you’re using the Site Editor, and you’ve activated a block-based theme like Twenty Twenty-Three, then you’ll definitely have access to a theme.json file.
But, if your chosen theme doesn’t come with a theme.json file, you can either switch themes or create your own file. It’s important to note that some themes come with very specific CSS or style blocks that might be incompatible with changes that you make in theme.json. For instance, the dark mode in Twenty Twenty-One cannot be overridden by stylistic changes added in theme.json.
What to do before editing your theme.json file
Now that you know a bit more about the theme.json file, let’s take a look at some important factors to consider before making your edits.
1. Back up your site
Before making any significant change, it’s important to make a backup of your site. That way, if something goes wrong, you can recover your website and start over again.
Using the Jetpack VaultPress Backup plugin is one of the easiest ways to back up your site.
This Jetpack tool creates real-time, cloud-based backups and stores them on WordPress.com’s secure server network. Plus, the restoration process is quick and simple.
You’re able to take advantage of one-click restores from the mobile app, even if your site is completely down.
2. Consider using a staging site
A staging site is a great way to test out changes you want to make without affecting your live website. Essentially, a staging site is a copy of your website that isn’t made available to the general public. Therefore, you’ll gain privacy to test out new features or update your site.
This way, you won’t need to worry about things going wrong when you edit the theme.json file. Furthermore, if there’s a problem, you’ll still be able to access your live site. It also means that when you finally push any changes to your live site, you can rest assured that they won’t harm the functionality of your pages.
There are a variety of ways that you can set up a staging site. You can ask your web host, set up different subdomains for your site manually, or install a plugin. But it can be easier to opt for a local WordPress development tool.
How to edit your theme.json file
At this point, you’re ready to access and edit your theme.json file! In this section, we’ll show you some useful ways to edit theme.json like creating a color palette and overriding the default font size for your blocks.
To get started, you’ll need to reach the root directory of your website. You can do this by using an SFTP client like FileZilla or visiting your File Manager. Then, simply head to the public_html directory. Within that, locate your wp-content folder.
Next, go to themes and select the active theme for your site. This is where you’ll find theme.json if your theme has one.
1. Create a default color palette
You might want to establish a set color palette for the Editor. That way, you can access your colors quickly and ensure a consistent visual brand across your pages.
Plus, it can be helpful if you have other users who create posts and pages on your site, since they’ll only be able to access the colors that you include within your color repository. Additionally, they won’t have the ability to create their own hues and gradients.
To get started, locate theme.json following the steps we outlined earlier. There are three factors to take into account to enable this setting:
- You’ll need to disable custom gradients
- You’ll need to disable custom color options
- You’ll need to add a custom palette with your brand colors
After you’ve connected to your theme files using SFTP or your File Manager, you’ll need to copy the following code and save it in the root directory of your theme:
{
“version”: 1,
“settings”: {
“color”: {
“custom”: false,
“customGradient”: false,
“gradients”:[],
“link”: false,
“palette”:[
{
“slug”: “vivadcyanblue”,
“color”: “#0693E3”
},
{
“slug”: “vividgreencyan”,
“color”: “#00D084”,
},
{
“slug”: “white”,
“color”: “#ffffff”
}
]
}Keep in mind, you’ll need to tweak the above code to reflect your preferences. Here, we’ve disabled the custom gradient and custom color options.
Plus, we’ve determined a set color palette of three different shades. Therefore, when users create posts and pages on the site, they’ll only be able to access these shades.
What’s great about creating a custom palette in theme.json is that WordPress will also rewrite all the required CSS. This way, any color changes made in the Block Editor will also be reflected on the front end.
2. Configure custom font sizes
It can also be useful to configure certain font sizes for the Paragraph block. Of course, the block provides a set of default font sizes, but you can use theme.json to override it with your preferences.
Again, you’ll need to find the root directory of your theme by visiting the themes folder in wp-content. Then, locate theme.json. Font sizes are added to theme.json under settings → typography → fontSizes.
Then, you’ll need to input your values. You’ll use size to add a valid CSS font size value. Meanwhile, slug is the identifier that WordPress uses in the CSS custom property. You can also add a name, but this is just for your own use since it’s what you’ll see in the editor.
In WordPress, the default “small” font size has the value 13px, so you can base your values around this. All in all, your theme.json file will look something like this once you’ve added this code to the file:
add_theme_support( 'editor-font-sizes', array(
array(
'name' => esc_attr__( 'Small', 'themeLangDomain' ),
'size' => 12,
'slug' => 'small'
),
array(
'name' => esc_attr__( 'Regular', 'themeLangDomain' ),
'size' => 16,
'slug' => 'regular'
),
array(
'name' => esc_attr__( 'Large', 'themeLangDomain' ),
'size' => 36,
'slug' => 'large'
),
array(
'name' => esc_attr__( 'Huge', 'themeLangDomain' ),
'size' => 50,
'slug' => 'huge'
)
) );Simply save the changes to update your WordPress block settings.
3. Create custom templates and template parts
Another way to edit theme.json is to create custom templates and template parts. Since themes can list the custom templates that are present in the templates folder, you can declare the post types that can use it and the title you show your users.
To get started, open theme.json. You’ll need to think of a name, title, and post type, although the last setting is optional. Then, add the following code to the file:
{
“version”: 1,
“customTemplates”: [
{
“name”: “custom-template-example”,
“title”: “The Custom Template Title”,
“postTypes”: [
“page”,
“post”,
“my-cpt”
]
}
]
}At this point, you’ve created a template for your pages, posts, and custom post types. You can go one step further and create template parts for your theme.
This way, you can configure theme.json to declare the area term for a template part, like a header or footer block. By defining this in theme.json, you can ensure that the setting is applied across all uses of that template part entity rather than just a single block.
Before you get started, you’ll need to consider the name, title, and area of your template part. It’s important to note that if you don’t specify an area, it will be set to “uncategorized” and trigger no block variation.
To create a template part for your theme, add the following code to theme.json:
{
“version”: 1,
“templateParts”: [
{
“name: “my-template-part”,
“title”: “Footer”,
“area”: “footer”
}
]
}Then, be sure to save your changes before exiting theme.json.
Frequently asked questions about theme.json in WordPress
Now you know how to edit theme.json, but you may still have a few doubts about it. That’s why we’ve answered some of the most common theme.json questions below!
When was theme.json first introduced in WordPress?
The theme.json file was first introduced with the release of WordPress 5.8. This is when Full Site Editing (FSE) was launched, along with the ability to use block-based themes.
This release indicated a huge shift for the platform, since users gained the ability to make site-wide changes and got more control over stylistic settings. Later, with WordPress 5.9, theme.json evolved to a second version.
What can you do with the theme.json file?
In short, theme.json enables you to change and apply new style-related settings to all of your WordPress blocks. Therefore, you gain a finer level of control over stylistic changes. Plus, it means you can avoid the need to configure these changes individually at the block level.
For example, you can edit theme.json to disable/enable features like drop cap, padding, margin, and custom line-height. Additionally, you’re able to add multiple color palettes, duotones, and gradients to make it faster to apply your brand colors to elements on your page.
What’s more, you can specify exact font sizes and apply this across your site. Or add default widths for your content and assign template parts to template part areas.
What are the prerequisites to using the theme.json file?
Editing theme.json is an easy way to make site-wide stylistic changes. But, unfortunately, it isn’t an option for all users.
First off, you’ll need to use the Block Editor. If you prefer to use page builders, you won’t be able to take advantage of this functionality. On top of that, you’ll need to have some understanding of CSS and feel comfortable editing your site files.
Lastly, you’ll need to be able to access theme.json. As we discussed earlier, not every theme has a theme.json file. Plus, the settings of some themes will override any changes that you make in theme.json.
If your theme does have theme.json, you’ll be able to find it in the root directory of your site. You can locate this using SFTP or visiting your File Manager. Then, find the themes folder within wp-content. This is where theme.json resides. If your theme does not have theme.json, you can either switch themes or create a theme.json file yourself.
Use the WordPress theme.json file for streamlined web design
Making custom, site-wide changes often means editing numerous files or completing lots of manual tasks. But, with theme.json, you’ll get a dedicated space for controlling and managing all the stylistic settings for your site.
The theme.json file is located in the root directory of your site from WordPress 5.8 onwards. You can edit the file to make sweeping changes like apply a custom color palette to your site and override the WordPress default font sizes.
Before you edit your theme.json file, it’s important to make a backup of your site. Jetpack VaultPress Backup is an easy-to-use plugin that enables you to restore your site even when you’re offline. Plus, it backs up all your files, WooCommerce data, and your database!
Explore the benefits of Jetpack
Learn how Jetpack can help you protect, speed up, and grow your WordPress site.
Get up to 50% off your first year.
Compare plans
Jetpack 