Global settings and styles

Welcome to this lesson where we will explore global settings and styles for WordPress.

Why does a WordPress theme need a theme.json file?

Theme.json is the configuration file for a theme. Previously, theme developers would have used the customizer to build out features for end users within their classic themes.

As an example, if we take a look at the classic theme Twenty Twenty-One, we would find the settings for colors and widgets within the Customizer. It is with the Customizer that end users work with the theme.

Today with modern WordPress, we have block themes and theme developers can now use theme.json to provide those features to end users. This provides a more consistent way of presenting features.

Within the Site Editor, you can see the possibilities for the settings and styles that you can include in your theme.

JSON format and the structure of theme.json

JSON stands for JavaScript Object Notation and is essentially a data representation format. It’s used for configuration files. It’s a common format for sending and requesting data through a REST API and it’s lightweight and easy to read.

The supported data types are strings, numbers, floats, booleans, arrays, and objects. With arrays, we always use a numeric index as we understand it in PHP as we see in the example shown.

With objects, we use a key value pair as this example here illustrates. This is a list of quotes from Westworld where you can see the key value format I was just mentioning.

Another thing to note is the key is always a string. In a code editor, you’ll find breadcrumbs at the top of the screen which are helpful for quickly navigating.

My cursor is on the first quote for Bernard Lowe and you can see that it is an array item. Another thing to note is with JSON, it’s particularly picky about commas. If I remove a comma, I get an error message.

Take a look at the theme.json file for the default theme Twenty Twenty-Four.

And we’ve got these properties I’m going to go over now.

Schema: used for defining the supported JSON. And this is why we get the on the fly hints and error reporting.

Version: for example version 2. You can always find this as a living reference on WordPress.org. It gives you the most up to date properties you can set.

Settings: used to define your block controls, color palettes, font sizes, and so on.

Styles: used to apply items such as colors, font sizes, custom CSS applied to the website and blocks.

Template parts: metadata for template parts defined in your themes parts folder.

Custom templates: metadata for custom templates defined in your themes templates folder.

Patterns: a comma separated list of slugs to be registered from the pattern directory available to us on WordPress.org.

Hierarchy used for loading the setting and style configurations

The theme.json file included in your theme is only one level in a hierarchy of setting and style configurations for a website. This means that it can be overridden under certain circumstances.

I’m going to walk you through from lowest to highest the priority of this hierarchy.

WordPress

Within the installation files, if you go to the WP includes folder, you’ll see theme.json there and this file defines the default settings and styles.

Theme theme.json file

Anything you define in that file will override the WordPress defaults. If you have a child theme that is active and you have a theme.json file included in your child theme, then anything that you do here will take precedence over the theme.json file in the parent theme. For instance you could set Appearance Tools to false.

User configurations

Within the Site Editor any changes that are added to the database through changes made to global styles or even templates and saved. This will override and takes priority over all other levels in the hierarchy.

Conclusion

Much more detailed information is available within the Intermediate Theme Developer Learning Pathway.

Don’t forget you can also visit the theme.json reference guide to further familiarize yourself with the JSON schema.