What Does WP Theme.JSON File Do and How To Use It – Simple Explanation

If you have started exploring WordPress block themes with full site editing capabilities, you must have learned about the much-hyped WP theme.json file. 

A WordPress development expert cited that the secret to designing beautiful websites and WordPress customizations is learning how to use the WP theme.json file. 

WP theme.json is where you can unlock capabilities like changing the default font of a theme, adding custom fonts, unlocking some settings that are not available in the block editor, or adding custom CSS. 

In this article, we will learn what the WP theme.json file is exactly, what purpose it serves, how WordPress was handling it previously in Classic themes, where to find it, and how to use it. 

Read this detailed comparison of WordPress block themes vs classic themes.

So without further ado, let’s begin this beginners’ tutorial on WP Theme.JSON. 

What is WP Theme.JSON?

WP Theme.JSON is essentially a global settings and styles configuration file that serves not one but multiple purposes. 

Unlike what some people might think, it is not a replacement for a style.css file. 

WordPress block themes still require the style.css file for configuring the theme metadata. 

However, after the introduction of WP theme.json, the number of lines of CSS code in style.css files has reduced. From 6000 lines of code in style.css in the Twenty Twenty One theme of WordPress, it has come down to just 149 lines of code in the Twenty Twenty Two theme, which introduced the WP theme.json file. 

WP Theme.JSON is written in JSON, which stands for JavaScript Object Notation. It’s a way of writing down information in a structured, easy-to-understand format. 

It’s like writing a shopping list where everything is neatly labeled and organized into categories. Here’s a simple example:

{

  "fruit": "Apple",

  "size": "Large",

  "color": "Red"

}

This tells you that you have an item that is a fruit, it’s an apple, its size is large, and its color is red. 

JSON is used because it’s easy for both humans and computers to read and write. It helps in transferring data between different parts of a website or between websites.

Here’s a table that summarizes the differences between theme.json and style.css in WordPress themes:

Feature	theme.json	style.css
Configuration vs. Styling	Allows configuring theme settings and default block styles, including block editor features like color palettes and layout settings.	Primarily used for defining CSS styles for the theme, without direct configuration of theme settings.
Global Styles	Enables setting global styles that apply site-wide, directly affecting how blocks appear by default. Users can override these styles in the site editor.	Requires manual CSS editing to change styles across the site, with no user override in the editor.
Editor Settings and Presets	Specifies which controls and settings are available in the block editor, tailoring the editing experience to match the theme’s design.	Classic themes lack a standardized method for managing block editor settings, often needing extra code in functions.php.
Format	Written in JSON (JavaScript Object Notation), it is structured and readable for both humans and machines. It allows for a declarative way of specifying theme configurations.	Written in CSS (Cascading Style Sheets), used for styling web pages. It doesn’t have direct capabilities for specifying theme configurations.

This table highlights the key differences in functionality and approach between theme.json and style.css, showing how theme.json offers a more integrated and user-friendly way to manage theme settings and styles in WordPress.

With that said, what purpose does the WP theme.json file serve? 

Uses of WP Theme.JSON File

The theme.json file in WordPress themes is a powerful tool for theme developers, offering a wide range of options for configuring and customizing a theme’s appearance and behavior. 

Let’s delve into the details of what you can do with each of the top-level properties mentioned:

1. Version

This property specifies the theme.json schema version your theme is using. It’s important because it tells WordPress which version of the theme.json specification your theme expects to work with, ensuring compatibility and enabling the use of the latest features. As the theme.json schema evolves, specifying the version helps maintain consistency and avoid potential issues with theme functionality.

2. $schema

The $schema property is used to define the supported JSON schema URL. This is particularly useful during theme development because many code editors can use this URL to fetch the schema and provide on-the-fly hints, autocomplete, and error reporting. It makes editing the theme.json file easier and helps prevent mistakes by ensuring that the file adheres to the expected structure and syntax.

3. Settings

The settings section is where you configure various global settings and block-specific controls for your theme. This includes:

• Enabling or disabling block editor features like custom color palettes, font size selections, and layout controls.
• Configuring presets for colors, gradients, font sizes, and more, which can be used throughout the site and in block editor controls.
• Setting defaults for typography, color, layout, and other aspects that affect both the block editor and the front end of the site.

This property significantly influences the editing experience, allowing theme developers to tailor the block editor to match the theme’s design and functionality.

4. Styles

With the styles property, you can define default styles that apply to the entire website and specific blocks. This includes:

• Setting global styles for elements like body text, links, headings, and more, ensuring a consistent look across the site.
• Applying block-specific styles, allowing for customization of block appearances directly from theme.json.
• Defining custom CSS properties (variables) that can be reused throughout the theme, enhancing maintainability and theme customization options.

5. customTemplates

This property allows you to provide metadata for WordPress custom templates that are defined within your theme’s /templates folder. You can specify template names, descriptions, and other attributes, making it easier to manage and select templates from the site editor. It’s a way to extend the default set of templates provided by WordPress or your theme with custom layouts and designs.

6. templateParts

Similar to customTemplates, the templateParts property is used for defining metadata for template parts (like headers and footers) located in your theme’s /parts folder. This includes setting human-readable names and area categories (e.g., header, footer) for template parts, facilitating easier selection and management within the site editor.

7. Patterns

The patterns property allows you to specify an array of pattern slugs that should be registered from the WordPress Pattern Directory. This enables theme developers to curate and recommend specific patterns to users of the theme, enhancing the design and layout options available directly from the block editor.

Comparing WP Theme.JSON More Deeply with Classic Themes

Before the introduction of theme.json with Full Site Editing (FSE) capabilities in WordPress, classic themes relied on a combination of PHP functions, CSS stylesheets, and additional theme files to manage and customize theme settings, styles, and functionalities. Here’s how WordPress handled various aspects of theme customization and configuration in classic themes:

Theme Settings and Customization

• Theme Options Page: Many classic themes included their own options page built with PHP, where users could change layout settings, color schemes, and other features. This required theme developers to create custom admin pages, handle form submissions, and manage settings storage in the WordPress database.
• Customizer API: WordPress provides a Customizer API that allows theme developers to add customizable options to the WordPress Customizer. This includes settings like colors, fonts, and layout options, which users can preview in real time. However, the extent of customization depended on what the theme developers chose to implement.

Styles and Appearance

• CSS Stylesheets (style.css): The primary way to style themes was through CSS. The main stylesheet, style.css, contained all the global styles for the theme. Themes could also include additional CSS files for specific sections or responsive design.
• Inline Styles and Functions: For dynamic styling (e.g., custom header colors or background images chosen by the user), themes often used inline styles added directly to the HTML output by PHP functions or hooks.
• Editor Styles: To mimic the website’s front-end styling within the WordPress editor, themes could provide a separate editor-style.css file. This allowed for a more consistent visual experience when creating and editing content but required manual maintenance to keep editor styles in sync with the theme’s front-end styles.

Functionality and Features

• functions.php File: The functions.php file in classic themes was the place to enqueue stylesheets and scripts, add theme support for various WordPress features (like post thumbnails, navigation menus, and post formats), and define custom functionality. This file could become quite complex and was central to extending and customizing a theme’s capabilities.
• Hooks and Filters: Classic themes made extensive use of WordPress hooks (actions and filters) to modify or extend the default behavior of WordPress. This included altering query results, customizing the read more text, modifying the excerpt length, and much more.
• Template Tags: WordPress provides a wide range of template tags that theme developers used within theme files to display content dynamically, such as post titles, content, metadata, and navigation links.

Template Files and Hierarchy

• Template Hierarchy: Classic themes relied on a specific set of PHP template files (e.g., index.php, single.php, page.php, archive.php) to control the display of different types of content. The WordPress template hierarchy determined which template file to use based on the query being requested.
• Hardcoded Templates and Partials: Themes often included multiple templates and partials (e.g., header.php, footer.php, sidebar.php) that were directly edited to change the layout or design of specific sections of the site.

In summary, classic themes managed customization and configuration through a mix of PHP, CSS, and WordPress-specific functions and APIs. 

While this system offered a high degree of flexibility and control, it also required more effort from theme developers to create customizable and maintainable themes. 

The introduction of theme.json streamlines many of these processes, offering a standardized, JSON-based configuration file that simplifies theme development and user customization.

Where to find WP Theme.JSON? 

To find or work with a theme.json file in a WordPress theme, especially if you’re dealing with a theme that supports Full Site Editing (FSE) or wants to adopt the new global styles and settings features, you would typically follow these steps:

The theme.json file is located in the root directory of a WordPress theme that supports the Full Site Editing features or wants to utilize the global styles and settings system.

How to Access WP Theme.JSON File

• Via WordPress Theme Editor: If you have admin access to a WordPress site, you can navigate to the theme editor by going to Appearance > Theme Editor in the WordPress admin dashboard. From there, select your theme and look for the theme.json file in the list of theme files. However, this method is not recommended for making changes, as it can lead to direct modifications that might break your site if not done correctly.
• Via FTP or File Manager: You can access your WordPress site’s files through FTP (File Transfer Protocol) or the file manager provided by your hosting service. Navigate to the /wp-content/themes/your-theme-name/ directory. Replace your-theme-name with the actual directory name of your theme. If your theme supports it, you will find the theme.json file there.
• Via Local Development Environment: If you’re developing or editing a theme locally, you can find the theme.json file in the theme’s directory within your local development environment. This is typically within wp-content/themes/your-theme-name/.

How to Create theme.json

If you’re developing a theme and it does not yet have a theme.json file, you can create one yourself. Simply open a text editor, create a new file, and save it as theme.json in the root of your theme’s directory. You can then start adding configurations to it following the WordPress theme.json schema.

Important Notes:

• Not all themes will have a theme.json file. This is particularly true for older themes or those not designed to take advantage of the latest Full Site Editing features in WordPress.
• When editing theme.json, it’s recommended to do so in a child theme or a testing environment first to prevent any unintended effects on your live site. Always back up your site before making changes.

How to Use and Edit WP Theme.JSON 

Using and editing the theme.json file in a WordPress theme allows you to define global settings and styles for your theme, taking advantage of the Full Site Editing (FSE) features. Here’s a guide on how to effectively use and edit theme.json:

Understanding theme.json Structure

Before editing, it’s crucial to understand the structure of theme.json. This file is organized into sections such as settings, styles, templateParts, and others, each responsible for different aspects of the theme’s behavior and appearance. Familiarize yourself with what each section does:

• settings: Controls available features and settings for blocks.
• styles: Defines default styles for your website, including colors, typography, and layout.
• templateParts: Details about template parts like headers and footers.
• customTemplates: Information about custom templates.

We’ve written a detailed blog post on WP theme.json layout. Check it out if you want to dive more into it.

Editing theme.json

1. Backup Your Site: Always back up your site before making changes, to avoid any potential loss of data.
2. Access the File:
   • If working locally, navigate to your theme directory (wp-content/themes/your-theme-name/) and open theme.json with a code editor.
   • If working on a live site, use FTP or a file manager to download theme.json from the same path, then open it with a code editor.
3. Make Your Edits:
   • Modify Settings: For example, to enable custom colors, within the settings object, find or add the color section and set custom to true.
   • Adjust Styles: To change the background color for the site, locate the styles section, then find or add the color and background properties to set your desired color.
   • Define Typography: To set a default font size or family, navigate to the styles section, find or add the typography section, and input your desired values.
4. Validate JSON: Ensure your theme.json is valid JSON. You can use online JSON validators to check your file for syntax errors.
5. Upload and Test:
   • If you made changes locally, upload the edited theme.json back to your theme’s directory on your server.
   • After uploading, visit your site and check the changes. Look for any visual or functional discrepancies.
6. Use Developer Tools for Troubleshooting: If something isn’t appearing as expected, use the browser’s developer tools to inspect elements and see if your styles are being applied. If not, there may be a specificity issue or a typo in your theme.json.

Tips for Editing

• JSON does not support comments. To keep notes, you might maintain a separate documentation file or a version of theme.json with comments that you remove before deploying.
• Use version control (like Git) to track changes to your theme.json file. This practice helps in managing updates and rolling back if necessary.
• If you’re modifying an existing theme, consider creating a child theme to preserve your changes during theme updates. You can include a theme.json in your child theme to override the parent theme’s settings and styles.

And that’s the end of our beginners’ guide to WP theme.json. 

If you want to learn about how to handle specific use cases with WP theme.json, refer to the following articles. 

How to Add Custom Fonts to WordPress in Theme.JSON

How to Add Custom Color Palette in WordPress in Theme.JSON