What Is theme.json File in WordPress and How to Use It

As WordPress has evolved, so have their themes. One thing you have to know about with WordPress themes is how to understand and use the theme.json file. In this article, you’ll learn what is theme.json in WordPress and how to use it.

Please note that this is not a beginner’s article and does contain code.

In WordPress, the theme.json file is a configuration file introduced with WordPress 5.8 as part of the Full Site Editing (FSE) feature.

This file is central to the block-based themes, providing a way to define global styles and settings for a theme. The introduction of theme.json aims to simplify the process of styling WordPress sites and make theme development more standardized and flexible.

Purpose and Benefits

Here are some of the purpose and benefits of the theme.json file in WordPress:

• Centralized Styling
• Consistency
• Customization

Centralized Styling

The theme.json file in WordPress serves as a single source of truth for theme styles. By consolidating all style-related configurations into one file, it eliminates the need for multiple CSS files and scattered inline styles, making the theme easier to manage and maintain.

Consistency

With theme.json, developers can ensure a consistent look and feel across the entire site. By defining global styles such as colors, typography, spacing, and layout options, the file ensures that all blocks and elements adhere to the same design principles.

Customization

The theme.json file supports user customization through the WordPress Customizer or the Site Editor. Users can adjust styles and settings without writing code, allowing for more accessible and user-friendly theme customization.

The theme.json file is written in JSON (JavaScript Object Notation) format. It typically includes the following key sections:

• Settings
• Styles
• Custom Templates and Template Parts

Settings

This section allows developers to define various settings that control the behavior of the editor and the available customization options. Settings include options for color palettes, font sizes, layout settings, and more.

   {
     "settings": {
       "color": {
         "palette": [
           {
             "slug": "primary",
             "color": "#000000",
             "name": "Primary"
           }
         ]
       },
       "typography": {
         "fontSizes": [
           {
             "slug": "small",
             "size": "12px",
             "name": "Small"
           }
         ]
       }
     }
   }

Styles

This section defines the default styles for various elements and blocks. It includes global styles (applied site-wide) and individual styles for specific blocks.

   {
     "styles": {
       "color": {
         "background": "#ffffff"
       },
       "typography": {
         "fontFamily": "Arial, sans-serif",
         "fontSize": "16px"
       },
       "blocks": {
         "core/paragraph": {
           "typography": {
             "fontSize": "14px"
           }
         }
       }
     }
   }

Custom Templates and Template Parts

With FSE, theme.json can also define templates and template parts, allowing for complete control over the layout and structure of the site’s pages and posts.

The theme.json file is located in the root directory of a theme. When WordPress loads the theme, it reads the theme.json file and applies the defined settings and styles across the site. This integration ensures that the styles are applied uniformly and that any changes made via the Customizer or Site Editor are reflected throughout the site.

Here are some ways that the theme.json file in WordPress are important to theme development:

• Simplified Development
• Enhanced Performance
• Future-Proofing

Simplified Development

By providing a standardized way to define styles and settings, theme.json reduces the complexity of theme development. Developers no longer need to write extensive custom CSS or PHP code for basic styling and configuration.

Enhanced Performance

With consolidated styles and reduced reliance on multiple CSS files, themes using theme.json can achieve better performance. Fewer HTTP requests and more efficient style management contribute to faster load times.

Future-Proofing

As WordPress continues to evolve towards full site editing and block-based themes, theme.json ensures that themes are compatible with future updates and features. It aligns with the long-term vision of WordPress, promoting a more modular and flexible approach to theme development.

The theme.json file in WordPress is a powerful tool to streamline and standardize the way themes are styled and configured. It allows developers to define global styles and settings for a theme in a single JSON file, making theme development more efficient and consistent. Here's a comprehensive guide on how to use the theme.json file in WordPress:

1. Setting Up the theme.json File
2. Understanding the Structure of theme.json
3. Defining Global Settings
4. Customizing Individual Blocks
5. Utilizing Custom Templates and Template Parts
6. Applying the theme.json Settings

Setting Up the theme.json File

To get started with the theme.json file, you need to create this file in the root directory of your theme. This file will be read by WordPress and used to apply the defined settings and styles across the entire site. Understanding the Structure of theme.json

The theme.json file is organized into several key sections:

• Version
• Settings
• Styles

Version

Indicates the version of the theme.json schema being used. As of now, version 1 is the standard.

Settings

Defines various global settings and customization options.

Styles

Specifies the default styles for global elements and individual blocks.

A basic structure of theme.json looks like this:

{
  "version": 1,
  "settings": {},
  "styles": {}
}

Defining Global Settings

The settings section is where you define various global settings that control the behavior of the editor and the available customization options. These settings include color palettes, font sizes, custom spacing, and layout options.

Example of Global Settings:

{
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "primary",
          "color": "#0073aa",
          "name": "Primary"
        },
        {
          "slug": "secondary",
          "color": "#005177",
          "name": "Secondary"
        }
      ],
      "gradients": [
        {
          "slug": "blue-to-green",
          "gradient": "linear-gradient(135deg, #0073aa, #11b8aa)",
          "name": "Blue to Green"
        }
      ]
    },
    "typography": {
      "fontSizes": [
        {
          "slug": "small",
          "size": "12px",
          "name": "Small"
        },
        {
          "slug": "large",
          "size": "24px",
          "name": "Large"
        }
      ]
    },
    "spacing": {
      "units": ["px", "em", "rem", "%"],
      "blockGap": "1.5rem"
    },
    "layout": {
      "contentSize": "800px",
      "wideSize": "1200px"
    }
  }
}

Defining Global Styles

The styles section is where you define the default styles for various elements and blocks. These styles ensure that your theme has a consistent look and feel across the entire site.

Example of Global Styles:

{
  "styles": {
    "color": {
      "background": "#ffffff",
      "text": "#333333"
    },
    "typography": {
      "fontFamily": "Arial, sans-serif",
      "fontSize": "16px",
      "lineHeight": "1.6"
    },
    "spacing": {
      "padding": "20px",
      "margin": "0 auto"
    },
    "blocks": {
      "core/paragraph": {
        "typography": {
          "fontSize": "18px"
        }
      },
      "core/heading": {
        "typography": {
          "fontFamily": "Georgia, serif",
          "fontWeight": "700"
        }
      }
    }
  }
}

Customizing Individual Blocks

In addition to global styles, you can also customize styles for individual blocks within the styles section. This allows for fine-grained control over the appearance of specific blocks.

Example of Block-specific Styles:

{
  "styles": {
    "blocks": {
      "core/paragraph": {
        "typography": {
          "fontSize": "18px",
          "lineHeight": "1.8"
        },
        "color": {
          "text": "#555555"
        }
      },
      "core/image": {
        "spacing": {
          "margin": {
            "top": "20px",
            "bottom": "20px"
          }
        }
      }
    }
  }
}

Utilizing Custom Templates and Template Parts

With Full Site Editing (FSE), the theme.json file can also define templates and template parts, allowing complete control over the layout and structure of the site’s pages and posts.

Example of Template Settings:

{
  "settings": {
    "customTemplates": [
      {
        "name": "my-custom-template",
        "title": "My Custom Template",
        "postTypes": ["page", "post"]
      }
    ]
  }
}

Applying the theme.json Settings

Once you have defined your settings and styles in the theme.json file, you need to activate your theme. WordPress will automatically read the theme.json file and apply the settings and styles across the site. This integration makes sure that any changes made via the Customizer or Site Editor are reflected throughout the site.

When handling the theme.json file in WordPress, here are just a couple best practice tips to keep in mind:

1. Start Simple
2. Keep It Organized
3. Leverage Documentation

Start Simple

Begin with basic global settings and styles, then gradually add more customization as needed.

Keep it Organized

Maintain a clear and organized structure within your theme.json file for readability and maintainability.

Leverage Documentation

Utilize the official WordPress documentation and resources to stay updated on best practices and new features related to theme.json.

In conclusion, the theme.json file in WordPress is a super important component in WordPress theme development, which offers a centralized, standardized, and flexible way to manage theme styles and settings. By following the steps outlined above, developers can effectively use theme.json to create themes that are consistent, customizable, and future-proof.