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 guide, 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. While it’s not a requirement to do so, if you only want your predetermined theme colors available to the user, you’ll need to do three things:
- Disable custom gradients
- Disable custom color options
- 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": 2,
"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 link, 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:
{
"version": 2,
"settings": {
"typography": {
"fluid": false,
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "13px"
},
{
"name": "Medium",
"slug": "medium",
"size": "20px"
},
{
"name": "Large",
"slug": "large",
"size": "36px"
},
{
"name": "Extra Large",
"slug": "x-large",
"size": "42px"
}
]
}
}
}Simply save the changes to update your WordPress block settings.
3. Create references to custom templates and template parts
Another way to edit theme.json is to create a reference to 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": 2,
"customTemplates": [
{
"name": "my-custom-template",
"title": "The 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": 2,
"templateParts": [
{
"name": "my-template-part",
"title": "Footer",
"area": "footer"
}
]
}Then, be sure to save your changes before exiting theme.json.
What to do if your site breaks when editing the theme.json file
If you save the theme.json file and the site editor goes white, or you see an error message saying “Invalid JSON,” don’t panic. This usually means you have a syntax error.
Check these three common mistakes:
- The Trailing Comma. You added a comma after the last item in a list. JSON hates this. Remove the last comma.
- Curly Braces. You opened a section with { but forgot to close it with }.
- Quotation Marks. You used single quotes ‘. JSON only accepts double quotes “.
If you cannot find the error. Copy your code. Paste it into a free online tool like JSONLint. It will point to the exact line number where the problem is.
Frequently asked questions
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.
What is the difference between theme.json and style.css in WordPress?
The main difference lies in how they function. style.css is a standard stylesheet that applies design rules using CSS code. theme.json is a configuration file that communicates directly with the WordPress editor interface.
While style.css only changes how the site looks on the frontend, theme.json controls both the frontend appearance and the backend editor settings. For example, you use theme.json to enable or disable specific features for users, such as custom colors or font sizes. It essentially manages the settings panel that users interact with. Modern block themes rely heavily on theme.json to generate CSS automatically, which often reduces the amount of code you need to write in style.css.
Can I use theme.json with a classic WordPress theme?
Yes. You can add a theme.json file to a classic PHP-based theme. This is often called a hybrid approach. It allows you to modernize an older theme without rebuilding it entirely from scratch.
When you add this file to a classic theme, it enables the new block editor styles and settings. It helps you control the typography, color palette, and layout options for any blocks used within your classic content areas. This is a smart way to gain the benefits of modern WordPress site editing, such as consistent global styles, while keeping your existing PHP templates for headers and footers.
How do I fix the “Invalid JSON” error in WordPress?
This error almost always happens because of a syntax mistake in your file. JSON is very strict about formatting. The most common cause is a trailing comma. This means you placed a comma after the last item in a list or group. You must remove that last comma for the file to work.
Another common issue involves quotation marks. You must use double quotes " for all properties and values. Single quotes ' will cause the file to break. If your site shows a white screen or an error message, copy your code and paste it into an online JSON validator tool. The tool will highlight the exact line number where the punctuation is incorrect so you can fix it quickly.
What is the difference between “settings” and “styles” in theme.json?
These two sections have distinct roles. The settings section controls the user interface in the block editor. It determines what tools are available to the content creator. For example, you use settings to define the color palette options, enable drop caps, or turn off custom font sizes.
The styles section applies the actual visual rules to the site. This is where you set the default look. If you want all headings to be blue and bold by default, you define that in styles. Think of settings as the configuration of the tools, and styles as the application of the design.
How can I disable default WordPress colors using theme.json?
You can disable the default colors to force users to stick to your specific brand palette. This prevents clients from choosing random colors that do not match your design. To do this, you need to modify the settings section of your file.
Inside settings.color, you must set defaultPalette to false. Once you do this, the standard WordPress colors (like the default blue or black) will disappear from the color picker. The user will only see the custom colors you explicitly define in your own palette array. This ensures strict brand consistency across the entire website.
Do child themes inherit settings from the parent theme.json?
Yes. Child themes inherit everything from the parent theme’s configuration file. However, the child theme can override specific parts of it. WordPress merges the two files together.
If the parent theme sets the background to white and the child theme sets it to gray, the child theme wins. You do not need to copy the entire file into the child theme. You only need to write the specific lines you want to change or add. This inheritance model makes it easy to create variations of a theme without duplicating code. It keeps your project clean and easier to maintain over time.
Does using theme.json improve website performance?
Yes. Using this file can improve site speed and Core Web Vitals scores. When you define styles in theme.json, WordPress generates CSS only for the blocks that are actually used on the page.
This is much more efficient than loading a massive style.css file that contains thousands of lines of code for elements that might not even exist on the current page. This approach reduces the total file size the browser needs to download. It also helps with Cumulative Layout Shift (CLS) because the layout settings are loaded early in the rendering process.
How do I add custom fonts to my WordPress theme locally?
You can register local font files directly within theme.json. This removes the need for external plugins or manual CSS @font-face rules. You define a fontFamilies array inside the settings.typography section.
For each font, you provide the name, the slug, and the file path to your local font files (like .woff2 files) stored in your theme folder. WordPress handles the loading of these assets automatically. Hosting fonts locally is better for privacy compliance (like GDPR) and performance because it eliminates the need to connect to third-party servers like Google Fonts.
Can I set different styles for specific blocks in theme.json?
Yes. You can target individual blocks to give them unique styles that differ from the global defaults. This is done inside the styles.blocks section.
For example, you might want your default paragraph text to be black, but you want the “Quote” block text to be italic and gray. You would open a specific entry for core/quote and apply those typography and color rules there. This allows for granular control over every element. It ensures that specific components look exactly how you want them to without writing complex CSS selectors manually.
Why are my changes in theme.json not showing up on the site?
There are two main reasons why changes might not appear immediately. The first is browser caching or server caching. Clear your browser cache or check your hosting dashboard to flush the managed cache.
The second reason is CSS specificity. If you have a separate CSS file that uses !important or very specific selectors, that code might override your theme.json settings. Additionally, if a user has manually changed a block’s color in the page editor, that manual choice takes priority over the global default. Check the specific page in the editor to see if a local override is active.
What WordPress version supports theme.json v3?
Theme.json version 3 was officially introduced in WordPress 6.6. If you are building a new block theme today, you should use version 3 to ensure your theme remains compatible with future updates.
This version introduced a significant change in how overrides work. In previous versions, your custom presets would automatically override the default core presets. In version 3, this behavior is more explicit, giving you greater control but requiring stricter configuration. If your site runs on an older version of WordPress (between 5.9 and 6.5), you must stick to version 2. However, since most live sites auto-update, version 3 is the safest choice for modern development.
Why aren’t my font sizes overriding the defaults?
This issue usually stems from the “Cascading” nature of CSS or a specific behavior in newer theme.json versions. First, check if you have manually set a font size on the specific block inside the WordPress editor. A manual change made by a user on a specific page always wins over the global defaults in your theme.json.
Second, if you are using version 3, the rules for overriding Core presets have changed. You might need to ensure your custom sizes use the exact same “slugs” (names) as the defaults if you intend to replace them entirely. Finally, inspect your site using the browser’s “Inspect Element” tool. Another plugin or a lingering style.css file might be loading a more specific CSS rule that forces the font size to remain unchanged.
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!
Jetpack 