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

Are you utilizing a block theme and seeing the theme.json file in WordPress? Perhaps you might be questioning what the aim of this file is and whether or not you must edit it.

The theme.json file is a vital a part of the total website modifying expertise in WordPress. As block themes grow to be extra widespread, it’s essential to grasp what theme.json does and easy methods to edit it correctly.

That’s why we at WPBeginner have put collectively this complete information. On this article, we are going to clarify what a theme.json file is and the way you need to use it to customise your WordPress website.

What Is the WordPress theme.json File?

The theme.json file is a particular theme file launched in WordPress 5.8. It performs a key position within the full site editing (FSE) expertise, which lets you visually customise each facet of your WordPress block theme.

Basically, the theme.json file acts as a blueprint that controls the styling and performance of your block theme. It incorporates code that tells WordPress how totally different parts like colours, typography, layouts, and templates ought to look and behave.

Why Do WordPress Block Themes Want a theme.json File?

Enhancing a block theme in WordPress is totally different from modifying a classic theme.

Traditional themes use the functions.php file to allow options like customized menus or featured photographs with the add_theme_support() perform. Then, you possibly can type these options with CSS guidelines within the CSS stylesheet (type.css) file.

In block themes, theme.json acts as a central hub for every thing that defines the feel and appear of your block theme. It permits you to outline issues like fonts, colours, and format choices in a single place, changing the necessity for add_theme_support() in capabilities.php.

That’s why the capabilities.php file in block themes is usually smaller than the equal in traditional themes.

Having a devoted theme.json file provides some nice advantages over the earlier traditional theme system.

First, theme.json works hand-in-hand with the WordPress full website editor. This lets you simply customize your theme’s styles and settings immediately throughout the editor without having to the touch any code.

Moreover, theme.json goals to create a constant expertise for each builders and customers. Some customers discover it actually irritating when they should change themes as a result of they must study fully new layouts and styling choices.

With theme.json, switching themes turns into a smoother course of as a result of every thing is organized in an analogous manner.

Lastly, by utilizing theme.json, theme builders and customers can future-proof their work as WordPress continues to increase its full website modifying capabilities.

Now that we’ve coated what a theme.json file is, let’s delve deeper into the subject. You should utilize the fast hyperlinks beneath to navigate by way of this information:

The place Do You Discover the WordPress theme.json File?

The theme.json file is discovered inside your theme listing in your internet server. The standard file path could be public_html » wp-content » themes » your-theme-name » theme.json.

To entry it, you first want to hook up with your website by way of FTP or your internet hosting account’s file supervisor.

If you happen to use Bluehost, then you possibly can log in and change to the ‘Web sites’ tab. Then, click on on the ‘Settings’ button beneath your web site.

Now, make certain to remain on the ‘Overview’ tab.

Then, scroll all the way down to click on on the ‘File Supervisor’ button.

Once you open the file supervisor this fashion, you’ll robotically be inside your web site’s root folder.

Right here, search for the ‘wp-content’ listing and open it. There, you’ll discover the ‘themes’ folder which incorporates all of your put in WordPress themes.

Open the folder for the particular block theme you’re utilizing. The theme.json file might be situated immediately inside this theme listing alongside different theme recordsdata.

Upon getting discovered it, you possibly can view the theme.json file utilizing a code editor.

What Does the theme.json File Look Like?

The theme.json file has a particular construction that organizes all the worldwide settings to your WordPress block theme.

Relying on how advanced or easy your theme appears to be like, the file may be very brief or lengthy. Nevertheless, you possibly can simply break this file down into 7 top-level sections:

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

Right here’s a simplified breakdown:

Schema

This half is definitely optionally available to have in block themes, so you could or could not see it in yours.

The schema property hyperlinks the URL to the WordPress JSON schema, which defines the worldwide settings, kinds, and different configurations to your theme.

Model

This part specifies which API model of the theme.json format is being utilized by the file and ensures it follows the proper construction.

As of the writing of this text, the API is at model 2.

Settings

This property defines the choices and controls out there for customers to customise their theme. These embody presets for the theme’s shade palette, typography, spacing, gradients, shadows, borders, and so forth.

Right here’s a quite simple instance of what the settings property appears to be like like:

{
  "settings": {
    "shade": {
      "palette": [
        {
          "slug": "base",
          "color": "#ffffff",
          "name": "White"
        },
        {
          "slug": "contrast",
          "color": "#222222",
          "name": "Dark"
        },
        {
          "slug": "accent",
          "color": "#f08080",
          "name": "Pink"
        },
        {
          "slug": "accent-2",
          "color": "#90ee90",
          "name": "Light Green"
        },
        {
          "slug": "accent-3",
          "color": "#e0ffff",
          "name": "Light 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": {
        "items": ["rem"],
        "values": {
          "small": "1rem",
          "medium": "1.5rem",
          "giant": "2rem"
        }
      }
    }
  }
}

If you happen to take a look at the code, the language used is fairly straightforward to grasp. You’ll be able to inform that the settings are defining the colours, font families, font sizes, and spacing used within the theme.

If there are any references right here or in your theme that you simply don’t perceive, you possibly can take a look at the official WordPress Settings Reference.

Some parts, like colours and font households, have slugs, like this:

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

These will come in handy for the styles section later on to make presets, which we will explain in the next part.

Styles

While the settings section defines the theme’s default customization options, the styles section applies them to the theme.

Here, you can apply the customization settings to the entire website or at a block level using presets.

Let’s check out 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"
      }
    }
  }
}

As you can tell, there is this line of code appearing throughout this snippet: var(--wp--preset--xxx) . These are presets, which are shortcuts in the styles section that refer back to the values defined in the settings section.

For example, consider {"slug": "base", "color": "#ffffff", "name": "White"} in the settings section. Here, "base" is the slug, and the corresponding preset for this color is var(--wp--preset--color--base) .

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

Custom Templates

Block theme developers can create predefined layouts for custom pages, posts, or post types for users to use.

For example, the Twenty Twenty-Four theme has several custom templates defined in the theme.json file: Page No Title, Page With Sidebar, Page with wide Image, and Single with Sidebar.

You can use any of these to create your content.

],
"customTemplates": [
  {
    "name": "page-no-title",
    "postTypes": ["page"],
    "title": "Web page No Title"
  },
  {
    "identify": "page-with-sidebar",
    "postTypes": ["page"],
    "title": "Web page With Sidebar"
  },
  {
    "identify": "page-wide",
    "postTypes": ["page"],
    "title": "Web page with huge Picture"
  },
  {
    "identify": "single-with-sidebar",
    "postTypes": ["post"],
    "title": "Single with Sidebar"
  }
]

One factor to notice is that the theme.json file solely references the templates by identify and supplies metadata about them, equivalent to their title and the put up sorts they’re supposed for.

Nevertheless, the precise look and performance of the customized templates are outlined in separate template recordsdata contained in the theme folder.

To see them, you possibly can go to public_html » wp-content » themes » your-theme-name » templates.

Template Elements

Template components are reusable areas you possibly can apply throughout your customized templates. These are parts like headers, footers, sidebars, and so forth.

Right here’s what these template components seem like 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"
  }
]

Like customized templates, the theme.json file solely references the templates.

Their precise look is outlined in their very own template half recordsdata within the components folder.

Patterns

Patterns are pre-made collections of blocks that allow you to create customized content material layouts in your pages, posts, or anyplace else in your theme.

Once you open the total website editor, you could discover the Patterns menu. That is the place you could find all of the out there patterns to your Gutenberg block theme.

With theme.json, theme builders can reference patterns from the general public Pattern directory. It’s an effective way to supply extra customization choices with out designing these reusable blocks your self.

For instance, the Twenty Twenty-4 theme references two patterns from the official listing: three columns of providers and shoppers part:

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

We all know this as a result of these patterns are within the Patterns menu within the full website editor.

Nevertheless, they’re not within the patterns folder contained in the theme listing.

What You Ought to Do Earlier than Enhancing the theme.json File

Since theme.json is a core theme file, modifying it immediately in your dwell WordPress website comes with some danger. Unintentional errors may doubtlessly break your theme or web site.

A safer strategy is to make use of a child theme.

A baby theme inherits all of the kinds and functionalities of your guardian theme (the block theme you might be utilizing) however permits you to customise issues with out modifying the parent theme itself. This manner, if the guardian theme receives updates, your customizations gained’t be overwritten.

You’ll be able to learn our information on how to create a child theme in WordPress for extra info. This text reveals a straightforward technique with the Create Block Theme plugin, which is able to robotically generate a brand new theme.json file to your baby theme solely.

To make sure a clean modifying expertise and keep away from any web site downtime, we additionally suggest creating a brand new backup of your WordPress website. This manner, if one thing goes incorrect, you possibly can simply restore your website to its earlier state.

We suggest utilizing a plugin like Duplicator for a fast and dependable backup resolution.

It’s additionally beneficial to work in a local WordPress development environment or a staging site. This creates a duplicate of your dwell web site the place you possibly can take a look at modifications safely with out affecting your guests.

Listed below are some extra suggestions to bear in mind:

• Start with minor edits in your theme.json file and take a look at them totally earlier than making extra advanced modifications.
• If you happen to’re uncertain about any particular property or setting throughout the theme.json file, seek the advice of the official WordPress documentation.
• Don’t hesitate to hunt assist from the theme developer’s assist group or the WordPress.org assist boards in the event you run into any points. Take a look at our information on how to ask for WordPress support for extra info.

Methods to Edit WordPress theme.json File

Primarily based on our analysis and testing, we’ve found two methods to edit a WordPress theme.json file: utilizing the full-site editor or utilizing code. The primary choice is way simpler and safer and allows you to see your modifications from the entrance finish of your web site.

In the meantime, the second selection is beneficial in case you are comfy with superior WordPress growth.

Edit theme.json With out Code (Rookies)

To edit your theme.json file with out touching the code immediately, you need to use the Create Block Theme plugin. This plugin was revealed by the official WordPress.org group to let customers create, edit, and save the type variations of their block theme.

First, go forward and set up the WordPress plugin in your admin space. Then, open the full-site editor by going to Look » Editor.

You’ll now see a number of menus to edit your theme.

Right here, choose ‘Kinds.’

Subsequent, click on the pencil ‘Edit kinds’ icon.

This can take you to the block editor to edit your web site’s international kinds.

Now, you possibly can change the type of your theme like regular. You’ll be able to learn the part on how to edit your theme’s global styles in our WordPress full-site modifying information for extra info.

Let’s strive making a customized shade palette for instance.

The color scheme or palette is a set of default colours for parts like textual content, backgrounds, and buttons. It ensures a cohesive look all through your web site.

Components utilizing the identical shade preset will at all times match in order that your web site design appears to be like polished {and professional}.

To edit the palette, choose ‘Colours’ on the Kinds settings sidebar.

On the following display screen, you will note some settings to customise your theme’s colours.

Right here, click on the colours within the ‘Palette’ part.

On this instance, the Twenty Twenty-4 theme has already outlined 5 colours within the palette, however you possibly can change any of them to create a customized one from scratch.

To take action, click on one of many colours beneath ‘Theme.’ Then, choose any shade within the shade picker instrument.

Now, in the event you preview your website, you will note that the particular blocks or parts that used the earlier shade have been changed with the colour you simply chosen in your palette.

You’ll be able to repeat the identical steps for every shade. Then, click on ‘Save.’

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

Then, choose ‘Save Adjustments to Theme.’

On the following display screen, you might want to scroll down.

After that, click on ‘Save Adjustments.’ This can immediate WordPress to retailer all of the modifications you’ve made to your theme within the theme.json file.

When you do this, the block editor will then refresh itself.

Now, click on the Create Block Theme button once more and choose ‘View theme.json.’

To see the code to your customized shade palette, search for palette that’s nested inside shade and settings, like so:

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

Underneath it, you must see the brand new hex codes of your customized shade palette.

Edit theme.json With Code (Superior Customers)

This technique is beneficial in case you are an aspiring WordPress theme developer or have some expertise with code.

First, open your block theme’s theme.json file in your WordPress listing. You’ll be able to both use the code editor in your internet host’s file supervisor or obtain the file, edit it in your pc, and add it again to your server.

We’ll use the Twenty Twenty-4 theme and Bluehost’s file supervisor for demonstration functions. If you’re a Bluehost person and are utilizing the file supervisor, then you possibly can simply merely right-click in your theme.json file and click on ‘Edit.’

If you happen to use FTP, then you possibly can learn our information on how to use FTP to upload files to WordPress.

Let’s strive a easy instance of modifying your theme.json file: creating customized font sizes.

Once more, do not forget that the settings property specifies your theme’s default kinds, whereas the kinds property implements them. For that reason, we are going to edit the settings property within the theme.json file.

If you happen to use a toddler theme, then you possibly can merely copy and paste the following code into your theme.json file and alter the font sizes in pixels as you see match:

{
  "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": "x-lagrge",  // Typo fixed (large -> large)
          "size": "48px"
        }
      ]
    }
  }
}

Observe: If you’re modifying your guardian theme’s file immediately, then you might want to discover the code that claims fontSizes .

It must be nested inside typography and settings , like so:

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

After that, substitute these traces of code with the code snippet from above. Simply ensure that there are not any syntax errors in it.

As soon as carried out, save the file and preview your web site to see your modifications. For Bluehost customers, you possibly can merely click on ‘Save Adjustments’ within the file supervisor’s code editor.

If you wish to edit your theme.json additional, we extremely encourage getting extra acquainted with the file’s construction as defined within the earlier part.

We additionally recommend studying the official WordPress Settings Reference, which features a full record of the out there settings properties and directions for utilizing them.

Bonus Tip: Use WPCode to Add Customized Code to Your Theme

On this information, you’ve discovered about theme.json and its potential for theme customization. However possibly it nonetheless feels a bit overwhelming to edit immediately.

Fortunately, there’s one other user-friendly choice for including customized code and making superior customizations: WPCode.

With WPCode, you possibly can insert custom code snippets with out ever needing to the touch your theme recordsdata themselves. This considerably reduces the chance of breaking your web site throughout customization.

If you wish to study extra about this code snippet plugin, take a look at our full WPCode review.

Additionally, listed here are some useful tutorials to get you began with utilizing WPCode:

We hope this text helped you study concerning the theme.json file in WordPress. You may additionally need to take a look at our newbie’s information on how to edit a WordPress website and our knowledgeable choose of the best drag-and-drop page builders for WordPress.

If you happen to preferred this text, then please subscribe to our YouTube Channel for WordPress video tutorials. You can too discover us on Twitter and Facebook.