Unlocking the Power of theme.json in WordPress: A Complete Guide to Usage and Benefits

The theme.json file is a crucial component of WordPress block themes, governing various aspects of your site’s design and functionality. If you’ve recently transitioned from a classic theme to a block theme, you might be curious about the purpose of this file and whether it requires any modifications.

You’re not alone in your curiosity. Many users at CanadaCreate have shared similar questions. That’s why we’ve decided to explore this topic thoroughly to offer you a detailed guide.

In this article, we will clarify what a theme.json file is, its significance, and how you can leverage it to personalize your WordPress site.

Understanding the WordPress theme.json File

The theme.json file is a unique theme file that was introduced in WordPress 5.8. It plays a vital role in the full site editing (FSE) experience, enabling you to visually customize every element of your WordPress block theme.

Essentially, the theme.json file serves as a blueprint that dictates the styling and functionality of your block theme. It includes code that instructs WordPress on how various elements, such as colors, typography, layouts, and templates, should be presented and function.

What is the Importance of the theme.json File for WordPress Block Themes?

Modifying a block theme in WordPress differs significantly from altering a classic theme.

Traditional themes utilize the functions.php file to enable features such as custom menus and featured images through the add_theme_support() function. You can then apply styles to these features using CSS rules in the stylesheet (style.css) file.

In block themes, theme.json serves as a central resource for defining the overall appearance and functionality of your block theme. It allows you to specify elements like fonts, colors, and layout options all in one location, eliminating the need for add_theme_support() in functions.php.

This is why the functions.php file in block themes is typically more streamlined compared to its counterpart in traditional themes.

Having a dedicated theme.json file provides significant advantages over the classic theme system.

Firstly, theme.json integrates seamlessly with the WordPress full site editor, enabling you to customize your theme’s styles and settings directly within the editor without requiring any coding skills.

Additionally, theme.json aims to deliver a consistent experience for both developers and users. Many users find it challenging to adapt when changing themes due to the need to learn entirely new layouts and styling options.

With theme.json, switching themes becomes a more streamlined experience as everything is organized in a consistent manner.

By utilizing theme.json, both theme developers and users can ensure their work remains relevant as WordPress enhances its full site editing capabilities.

Having explained what a theme.json file is, let’s explore the topic further. Use the quick links below to navigate this comprehensive guide:

Where Can You Locate the WordPress theme.json File?

The theme.json file is located within your theme directory on your web server. The typical file path is:public_html » wp-content » themes » your-theme-name » theme.json.

To access it, you must first connect to your site using FTP or the file manager provided by your hosting account.

If you’re using Bluehost, log in and navigate to the ‘Websites’ tab. Then, click on the ‘Settings’ button located below your website.

Ensure you remain on the ‘Overview’ tab.

Next, scroll down and click on the ‘File Manager’ button.

When you access the file manager this way, you will be taken directly to the root folder of your website.

In this folder, locate the ‘wp-content’ directory and open it. Inside, you will find the ‘themes’ folder, which contains all the WordPress themes you have installed.

Open the folder for the specific block theme you are using. The theme.json file will be located directly within this theme directory alongside other theme files.

Once you locate it, you can open the theme.json file using a code editor.

What is the Structure of the theme.json File?

The theme.json file has a defined structure that organizes all the global settings for your WordPress block theme.

Depending on the complexity of your theme, the file may be short or long. However, it can be easily categorized into 7 main sections:

{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"settings": {},
"styles": {},
"customTemplates": {},
"templateParts": {},
"patterns": []
}

Here’s a simplified overview:

Schema

This section is optional in block themes, so you may or may not find it in your theme.

The schema property connects the URL to the WordPress JSON schema, which outlines the global settings, styles, and other configurations for your theme.

Version

This section indicates the API version of the theme.json format being utilized by the file, ensuring it adheres to the proper structure.

As of the publication of this article, the API is currently at version 2.

Settings

This property outlines the options and controls available for users to personalize their theme. These options include presets for the theme’s color palette, typography, spacing, gradients, shadows, borders, and more.

Here’s a straightforward example of how the settings property is structured:

{ "settings": { "color": { "palette": [ { "slug": "base", "color": "#ffffff", "name": "White" }, { "slug": "contrast", "color": "#222222", "name": "Dark Gray" }, { "slug": "accent", "color": "#f08080", "name": "Soft Pink" }, { "slug": "accent-2", "color": "#90ee90", "name": "Pale Green" }, { "slug": "accent-3", "color": "#e0ffff", "name": "Sky Blue" } ] }, "typography": { "fontFamilies": [ { "fontFamily": "Open Sans, sans-serif", "slug": "open-sans", "name": "Open Sans" }, { "fontFamily": "Arial, sans-serif", "slug": "arial", "name": "Arial" }, { "fontFamily": "Times New Roman, serif", "slug": "times-new-roman", "name": "Times New Roman" } ], "fontSizes": [ { "name": "Extra Small", "slug": "xx-small", "size": "0.75rem" }, { "name": "Small", "slug": "small", "size": "0.875rem" }, { "name": "Medium", "slug": "medium", "size": "1rem" }, { "name": "Large", "slug": "large", "size": "1.125rem" }, { "name": "Extra Large", "slug": "x-large", "size": "1.25rem" }, { "name": "XX-Large", "slug": "xx-large", "size": "1.5rem" } ], "spacing": { "units": ["rem"], "values": { "small": "1rem", "medium": "1.5rem", "large": "2rem" } } } }
}

The code is straightforward and easy to comprehend. It clearly outlines the settings for colors, font families, font sizes, and spacing utilized in the theme.

If you encounter any unfamiliar references in this document or within your theme, you can consult the official WordPress Settings Reference for clarification.

Certain elements, such as colors and font families, are identified by slugs, like this:

{ "settings": { "color": { "palette": [ { "slug": "base", "color": "#ffffff", "name": "White" },

These will be useful for creating presets in the styles section, which we will elaborate on in the next section.

Styles

While the settings section establishes the default customization options for the theme, the styles section applies these settings throughout the theme.

Here, you can implement the customization settings across the entire website or at the block level using presets.

Let’s take a look at the example below:

{ "settings": { // Existing settings from the previous example }, "styles": { "color": { "background": "var(--wp--preset--color--base)", "text": "var(--wp--preset--color--contrast)" }, "elements": { "link": { "color": { "text": "var(--wp--preset--color--accent-2)" } }, "h1": { "fontSize": "var(--wp--preset--font-size--xx-large)", "lineHeight": "1.2", "marginBottom": "1rem" }, "h2": { "fontSize": "var(--wp--preset--font-size--x-large)", "lineHeight": "1.2", "marginBottom": "1rem" }, "h3": { "fontSize": "var(--wp--preset--font-size--large)", "lineHeight": "1.2", "marginBottom": "1rem" } } }
}

Throughout this code snippet, you will notice the following line of code: var(--wp--preset--xxx). These are called presets, which serve as shortcuts in the styles section that reference values defined in the settings section.

For instance, take a look at {"slug": "base", "color": "#ffffff", "name": "White"} found in the settings section. In this case, "base"represents the slug, and the associated preset for this color isvar(--wp--preset--color--base).

Thus, the code"color": {"background": "var(--wp--preset--color--base)"in the styles indicates that the background color of this theme is white.

Custom Templates

In the development of WordPress block themes, developers can design predefined layouts for custom pages, posts, or custom post types that users can utilize.

For instance, the Twenty Twenty-Four theme includes several custom templates specified in the theme.json file: Page Without Title, Page With Sidebar, Page with Wide Image, and Single Post with Sidebar.

You can select any of these templates to create your content.

],
"customTemplates": [ { "name": "page-no-title", "postTypes": ["page"], "title": "Page Without Title" }, { "name": "page-with-sidebar", "postTypes": ["page"], "title": "Page With Sidebar" }, { "name": "page-wide", "postTypes": ["page"], "title": "Page with Wide Image" }, { "name": "single-with-sidebar", "postTypes": ["post"], "title": "Single Post with Sidebar" }
]

It’s important to understand that the theme.json file references templates by name and includes metadata such as their titles and the post types they are designed for.

The actual design and functionality of the custom templates are defined in separate template files located within the theme folder.

To access these files, navigate to public_html » wp-content » themes » your-theme-name » templates.

Template Parts

Template parts are reusable components that can be utilized across your custom templates. These include elements such as headers, footers, and sidebars.

Here’s how those template parts are registered in theme.json:

"templateParts": [ { "area": "header", "name": "header", "title": "Header" }, { "area": "footer", "name": "footer", "title": "Footer" }, { "area": "sidebar", // Removed "uncategorized" "name": "sidebar", "title": "Sidebar" }, { "area": "post-meta", // Removed "uncategorized" "name": "post-meta", "title": "Post Meta" }
]

Similar to custom templates, the theme.json file solely references the templates.

The actual appearance of these elements is defined in their respective template part files located in the parts folder.

Patterns

Patterns are pre-designed collections of blocks that enable you to create customized content layouts for your pages, posts, or any part of your theme.

When you access the full site editor, you will see the Patterns menu. This section displays all the available patterns for your Gutenberg block theme.

With theme.json, theme developers can utilize patterns from the public Pattern directory. This provides an excellent way to enhance customization options without the need to create these reusable blocks from scratch.

For instance, the Twenty Twenty-Four theme incorporates two patterns from the official directory: a three-column services layout and a clients section:

"patterns": [ "three-columns-of-services", "clients-section"
]

We can confirm this because these patterns are listed in the Patterns menu within the full site editor.

However, they are not located in the patterns folder within the theme directory.

Essential Steps to Take Before Modifying the theme.json File

As theme.json is a critical file for your theme, making direct edits on your live WordPress site carries some risks. Mistakes could potentially disrupt your theme or website functionality.

A more secure option is to implement a child theme.

A child theme inherits all the styles and features of your parent theme (the block theme you are currently using) while allowing you to make customizations without altering the parent theme itself. This ensures that any updates to the parent theme won’t erase your custom changes.

For further details, you can refer to our guide on creating a child theme in WordPress. This article provides a straightforward method using the Create Block Theme plugin, which will automatically create a new theme.json file specifically for your child theme.

To maintain a seamless editing experience and prevent any website downtime, we highly recommend creating a fresh backup of your WordPress site. This ensures that you can quickly restore your site to its previous state if anything goes wrong.

Consider using a plugin such as Duplicatorfor an efficient and dependable backup solution.

It’s advisable to work within a local WordPress development environment or a staging site. This allows you to create a duplicate of your live website where you can safely test changes without impacting your visitors.

Here are additional tips to keep in mind:

• Start with small edits in your theme.json file and thoroughly test them before proceeding with more complex modifications.
• If you have questions about any specific property or setting in the theme.json file, refer to the official WordPress documentation.
• Don’t hesitate to reach out to the support team of your theme developer or the WordPress.org support forums if you encounter any issues. For more guidance, check out our article on how to request WordPress support.

How to Modify the WordPress theme.json File

Our research and testing have revealed two methods for editing a WordPress theme.json file: using the full-site editor or editing the code directly. The first method is simpler and safer, allowing you to preview your changes on the front end of your website.

The second method is advisable for those who are experienced with advanced WordPress development.

Editing theme.json Without Code (For Beginners)

To modify your theme.json file without coding, you can utilize the Create Block Theme plugin. This plugin, developed by the official WordPress.org team, enables users to create a custom block theme, make edits, and save style variations.

Start by installing the WordPress plugin in your admin dashboard. Then, access the full-site editor by navigating to Appearance » Editor.

You will now see various menus to customize your theme.

Select ‘Styles’ from the options.

Next, click on the pencil icon labeled ‘Edit styles.’

This will direct you to the block editor where you can adjust your website’s global settings and styles.

You can now modify your theme’s style as you would normally. For more details, refer to the section on editing your theme’s global styles in our WordPress full-site editing guide.

Let’s create a custom color palette as an example.

A color scheme or palette consists of default colors for various elements such as text, backgrounds, and buttons, ensuring a unified appearance across your website.

Elements that share the same color preset will consistently match, giving your website design a refined and professional look.

To modify the color palette, click on ‘Colors’ in the Styles settings sidebar.

On the following screen, you will find options to customize the colors of your theme.

Here, click on the colors in the ‘Palette’ section.

In this example, the Twenty Twenty-Four theme has predefined five colors in the palette, but you can adjust any of them to create a custom palette from scratch.

To do this, click on one of the colors under ‘Theme’ and choose any color from the color picker tool.

Now, when you preview your website, you will notice that the specific blocks or elements that previously used the old color have been updated to the new color you selected in your palette.

You can follow the same steps for each color, and then click ‘Save.’

After saving your changes, click the Create Block Theme button (the wrench icon).

Then, select ‘Save Changes to Theme.’

On the next screen, you will need to scroll down.

After that, click ‘Save Changes.’ This action will ensure that WordPress saves all the modifications you’ve made to your theme in the theme.json file.

Once you do that, the block editor will refresh automatically.

Now, click the ‘Create Block Theme’ button again and select ‘View theme.json.’

To view the code for your custom color palette, look for palette located within color and settings, as shown below:

"settings": { // Some code... "color": { // Some code... "palette": }
}

Below it, you should see the new hex codes for your custom color palette.

Edit theme.json with Code (For Advanced Users)

This method is ideal if you are an aspiring WordPress theme developer or have some coding experience.

First, open your block theme’s theme.json file located in your WordPress directory. You can either use the code editor provided by your web host’s file manager or download the file, edit it on your computer, and then upload it back to your server.

For our demonstration, we will utilize the Twenty Twenty-Four theme along with Bluehost’s file manager. If you are a Bluehost customer and using the file manager, you can easily right-click on your theme.json file and select ‘Edit.’

If you prefer using FTP, you can refer to our guide on how to upload files to WordPress via FTP.

Let’s explore a straightforward example of modifying your theme.json file by creating custom font sizes.

Keep in mind that the settings property defines your theme’s default styles, while the styles property applies them. Therefore, we will focus on editing the settings property within the theme.json file.

If you are working with a child theme, you can simply copy and paste the following code into your theme.json file and adjust the font sizes in pixels to your preference:

{ "settings": { "typography": { "fluid": false, "fontSizes": [ { "name": "Small", "slug": "small", "size": "16px" }, { "name": "Medium", "slug": "medium", "size": "24px" }, { "name": "Large", "slug": "large", "size": "40px" }, { "name": "Extra Large", "slug": "extra-large", "size": "48px" } ] } }
}

Important Note: If you are directly editing the files of your parent theme, locate the code that reads fontSizes .

This should be found within the typography and settings sections, formatted like this:

{ "settings": { // Additional code... "typography": { // Additional code... "fontSizes": [ // Font size definitions go here ] } }
}

Next, replace those lines of code with the provided code snippet above. Ensure there are no syntax errors.

After completing your changes, save the file and preview your website to see the updates. If you are using Bluehost, simply click ‘Save Changes’ in the code editor of the file manager.

To further edit your theme.json file, we recommend familiarizing yourself with its structure as detailed in the previous section.

We also recommend reviewing the official WordPress Settings Reference, which provides a comprehensive list of available settings properties and guidance on how to use them.

Pro Tip: Utilize WPCode to Integrate Custom Code into Your Theme

In this guide, you have discovered the capabilities of theme.json for customizing your theme. However, editing it directly may still seem daunting.

Fortunately, there is a more user-friendly way to add custom code and make advanced customizations: WPCode.

With WPCode, you can add custom code snippets without modifying your theme files, greatly minimizing the risk of disrupting your website during the customization process.

To learn more about this code snippet plugin, be sure to read our comprehensive WPCode review.

Additionally, here are some useful tutorials to help you get started with WPCode:

• Essential WordPress Code Snippets for Beginners (Expert Recommendation)
• How to Feature New Posts for Returning Visitors in WordPress
• How to Emphasize Text in WordPress
• A Simple Guide to Adding Box Shadows in WordPress

We hope this article has helped you understand the theme.json file in WordPress. You might also find our beginner’s guide on editing a WordPress website and our top recommendations for the best drag-and-drop page builders for WordPress useful.

If you enjoyed this article, please subscribe to our YouTube Channel for WordPress video tutorials. You can also connect with us on Twitter and Facebook.