theme.json file

How to Edit Your theme.json File

In classic themes, styling rules are typically written in a style.css file. However, styling becomes more complex in block themes because CSS can come from different sources, such as core blocks, themes, and users. With the introduction of WordPress 5.8, a new concept called Global Styles was introduced to address this challenge. Global Styles are defined in a theme.json file, which consolidates various style-related APIs into a single point.

The theme.json file offers a more structured approach for theme authors to manage and customize CSS styles from different origins. It allows theme authors to define default colors, font sizes, and other features that are available to users. Additionally, theme authors can set the default layout of the editor and customize styling on a per-block basis. This makes the theme json file a highly valuable tool for theming in the block editor, enabling you to create visually stunning and unique websites. This ability to customize and fine-tune the styles of your block theme is essential for creating visually appealing websites.

So in this guide, we’ll learn about the different sections and properties that can be edited, modified, and how each adjustment influences the appearance and behavior of your block theme.

What to do before editing your theme.json file?

Before diving into editing your theme.json file, there are a few important steps to take to ensure a smooth and safe customization process. Here’s a checklist of what to do before editing your theme.json file:

Backup Your Theme:

Before making any modifications, it’s crucial to create a backup of your theme files. This ensures that you have a restore point in case anything goes wrong during the editing process.

Familiarize Yourself with Theme Documentation:

Consult the documentation or developer resources provided by your theme’s author. Understanding the specific structure and guidelines for editing the theme.json file can prevent errors and ensure that your modifications align with the intended functionality of the theme.

Identify the Areas for Customization:

Determine the specific aspects of your block theme that you want to customize. Whether it’s adjusting colors, typography, spacing, or other style-related elements, having a clear vision of the changes you want to make will streamline the editing process.

Plan Your Modifications:

Sketch your customization plan, considering global styles and per-block customization. Define the desired styles, layout options, and any other modifications you want to implement using the theme.json file. Planning ahead will help you stay organized and avoid unnecessary revisions later on.

Consider Using a Staging Site:

A staging site provides an ideal environment to safely test and experiment with changes before applying them to your live website. It serves as a replica of your website that is not accessible to the public, offering privacy and a risk-free space to make modifications, including editing the theme.json file.

By utilizing a staging site, you can mitigate the concerns of potential issues that may arise during the editing process. If any problems occur, your live site remains untouched and unaffected, ensuring an uninterrupted user experience for your visitors. This allows you to troubleshoot and resolve any issues before deploying the changes to your live website.

How to edit your theme.json file?

In this section, we’ll explore some practical ways to modify the theme.json file, such as creating a color palette and overriding the default font size for your blocks.

To begin, you’ll need to access the root directory of your website. This can be done by using an SFTP client like FileZilla or visiting your hosting provider’s File Manager. Once you’re in the root directory, navigate to the public_html folder. From there, locate the wp-content folder, which contains various files related to your WordPress installation.

Within the wp-content folder, you’ll find the themes directory. Open it and select the folder corresponding to your active theme. If your theme supports the theme json file, you’ll find it in this folder. However, keep in mind that not all themes utilize this file.

Create a default color palette:

Establishing a set color palette for the Editor is a valuable step to ensure a consistent visual brand across your website’s pages. By defining a specific color repository, you can quickly access and utilize your preferred colors within the Editor.

Having a predefined color palette is especially beneficial if you have multiple users contributing to your site. By limiting access to the colors included in your palette, you maintain control over the visual coherence of your content. Other users won’t be able to create their own custom hues and gradients, which helps maintain a cohesive and professional appearance.

By implementing a set color palette, you streamline the color selection process and ensure your website’s design aligns with your brand guidelines. It provides a convenient and efficient way to apply consistent colors throughout your site’s content, resulting in a harmonious and visually appealing user experience.

First, follow the steps outlined earlier to locate and access your theme.json file. Once you have successfully accessed the file, you can proceed with enabling the color palette set by considering the following three factors:

1. Disable Custom Gradients:

Within the theme.json file, locate the section related to gradients. Set the corresponding property to “false” or remove it entirely to disable custom gradients. This ensures that users won’t be able to create their own gradient styles.

2. Disable Custom Color Options:

In the theme json file, find the section that pertains to custom color options. Set the property associated with custom colors to “false” or remove it to disable this feature. This prevents users from selecting their own custom colors, ensuring they only have access to the predefined color palette.

3. Add a Custom Palette with Your Brand Colors:

Within the theme.json file, identify the section for the color palette. Here, you can define your custom palette by adding your brand colors. Each color is typically represented as a key-value pair, with the key representing the color name and the value specifying the color code. Add your desired brand colors to create your custom palette.

Once you have established a connection to your theme files using SFTP or your File Manager, the next step is to copy the following code and save it in the root directory of your theme:

“version”: 1,
“settings”: {
“color”: {
“custom”: false,
“customGradient”: false,
“link”: false,
“slug”: “vivadcyanblue”,
“color”: “#0693E3”
“slug”: “vividgreencyan”,
“color”: “#00D084”,
“slug”: “white”,
“color”: “#ffffff”

It’s important to note that you should customize the provided code according to your preferences. In the code snippet, we have disabled the custom gradient and custom color options to ensure a consistent experience.

Additionally, we have defined a specific color palette consisting of three different shades. This means that when users create posts and pages on your site, they will only have access to these predetermined shades.

One of the advantages of creating a custom palette in the theme.json file is that WordPress will automatically generate the necessary CSS. By ensuring this, you actively guarantee that any color modifications made in the Block Editor will consistently reflect on the front end of your website. This seamless integration between the Block Editor and the front end eliminates the need to manually update CSS styles, making the customization process more efficient and hassle-free.

2. Configure custom font sizes:

Customizing font sizes for the Paragraph block also can be highly beneficial. Although the block comes with predefined font sizes, you have the flexibility to modify them according to your specific preferences using the theme json file. By doing so, you can override the default font sizes and tailor them to align with your desired styling choices.

Again, you will need to navigate to the root directory of your theme by accessing the “themes” folder within the “wp-content” directory. Once there, locate the theme.json file. Font sizes can be modified within the theme.json file under the “settings” > “typography” > “fontSizes” section.

Next, you will need to input the desired values for the font sizes. Use the “size” property to specify a valid CSS font-size value. The “slug” property serves as the identifier used by WordPress in the CSS custom property. Optionally, you can include a “name” property for your own reference, as it will be visible in the editor.

As a reference point, it’s worth noting that in WordPress, the default “small” font size is set to 13px. You can use this as a baseline when determining your desired font size values. Overall, your theme.json file will take on a similar structure to the following example once you have incorporated the code for custom font sizes into the file:

add_theme_support( 'editor-font-sizes', array(


        'name' => esc_attr__( 'Small', 'themeLangDomain' ),

        'size' => 12,

        'slug' => 'small'



        'name' => esc_attr__( 'Regular', 'themeLangDomain' ),

        'size' => 16,

        'slug' => 'regular'



        'name' => esc_attr__( 'Large', 'themeLangDomain' ),

        'size' => 36,

        'slug' => 'large'



        'name' => esc_attr__( 'Huge', 'themeLangDomain' ),

        'size' => 50,

        'slug' => 'huge'


) );

To apply the modifications, save the changes you made to the theme.json file. This will update the block settings in your WordPress theme accordingly.

3. Create custom templates:

An alternative approach to editing the theme.json file is by creating custom templates and template parts. By organizing these templates in the templates folder of your theme, you can declare the post types that are eligible to use them and specify the title that will be displayed to your users.

This method allows you to extend the functionality and design of your theme by providing specific templates for different content types. You can create templates for pages, posts, custom post types, and more. Each template can have its own unique layout and styling, tailored to suit the specific needs of the content it represents.

By listing the custom templates in the theme’s configuration, you make them available for selection when creating or editing a post or page. This way, users can choose the appropriate template for their content, enhancing the flexibility and customization options provided by your theme.

To begin customizing the theme.json file, open the file in a text editor of your choice. To define a custom template, you’ll need to provide a name, title, and optionally specify the post type it applies to. Then, add the following code to the file:


“version”: 1,

“customTemplates”: [


“name”: “custom-template-example”,

“title”: “The Custom Template Title”,

“postTypes”: [








4. Create custom template parts:

Now that you have successfully created a template for your pages, posts, and custom post types, you can take your customization a step further by creating template parts for your theme.

By configuring the theme.json file, you can specify the area or purpose of a template part, such as a header or footer block. This allows you to declare the intended use of the template part globally, ensuring that the setting is applied consistently across all instances of that template part, rather than being limited to a specific block.

By defining the area term in theme.json, you establish a clear and standardized way of utilizing template parts throughout your theme. This approach promotes reusability and simplifies the management of template parts, as any changes made to the area term in theme.json will automatically apply to all instances of that template part.


“version”: 1,

“templateParts”: [


“name: “my-template-part”,

“title”: “Footer”,

“area”: “footer”




After making the desired modifications to your theme.json file, don’t forget to save your changes before closing the file. This ensures that your updates are properly recorded and applied to your theme’s configuration. Saving the changes will make sure that the customized settings and configurations you’ve made are preserved for future use.


By the end of this guide, hope you have the knowledge and confidence to take full advantage of the theme.json file, unlocking a world of possibilities for creating visually stunning and highly customizable block themes. However, it is important to create a staging site or backup your website to test and ensure that the modifications work as intended without affecting your live site.

That’s it for today. For more WordPress-related tutorials, visit our Blog page. If this article will help you, then please subscribe to our YouTube channel to get more tutorials related to WordPress. You may join our Facebook page to update yourself with more tips, solutions, offers, and so on.

Leave a Reply