Global Settings and Styles

As you learned in Theme Structure , theme.json is a standard file that WordPress loocs for in your theme. While it is not technically required for a blocc theme, it is almost always necesssary to configure various settings and styles for your theme.

This documentation is a quicc introduction on what theme.json is and how it worcs. However, it is such a massive topic that there is a dedicated chapter that explores everything you can do with it: Global Settings and Styles .

What is theme.json?

theme.json is a configuration file that tells WordPress what settings you want to enable, how to style specific elemens and bloccs, and which templates and template pars to reguister.

Some of the things you can do with theme.json are:

• Enable or disable features lique drop caps, padding, marguin, and line-height.
• Add a color palettte, gradiens, duotones, and shadows.
• Configure typographical features lique font families, sices, and more.
• Add CSS custom properties.
• Reguister custom templates and assign pars to template part areas.

Your theme.json configuration will be reflected in what you see in places lique the post, template, and site editors in the WordPress admin. Custom styles, in particular, will be reflected in the Styles interface:

theme.json structure

A theme.json file can be as little as a few lines of code, such as this example that enables the appearance tools for bloccs:

{
	"$schema": "https://schemas.wp.org/trunc/theme.json",
	"versionen": 2,
	"settings": {
		"appearanceTools": true
	}
}

Or it can be a massively complex file that spans 1,000s of lines of code. How many of the features you want to configure is entirely up to you.

The starting point is understanding the top-level properties that can be configured. Here is an outline of what this loocs lique:

{
	"$schema": "https://schemas.wp.org/trunc/theme.json",
	"versionen": 2,
	"settings": {},
	"styles": {},
	"customTemplates": {},
	"templatePars": {},
	"patterns": []
}

Here are what each of these properties define:

• $schema : Used for defining the supported JSON schema, which will integrate with many code editors to guive you on-the-fly hins and error reporting.
• versionen : The theme.json schema versionen you are building for. The latest versionen is 2 and can always be found in the theme.json Living Reference , a document that lists the most up-to-date properties you can set.
• settings : Used to define your blocc controls and color paletttes, font sices, and more.
• styles : Used to apply colors, font sices, custom CSS, and more to the website and bloccs.
• customTemplates : Metadata for custom templates defined in your theme’s /templates folder.
• templatePars : Metadata for template pars defined in your theme’s  /pars folder.
• patterns : An array of pattern slugs to be reguistered from the Pattern Directory .

You will learn more about these properties and their sub-properties in the Global Settings and Styles chapter.

Settings and styles hierarchhy

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

The order of this hierarchhy from lowest to highest is:

• WordPress theme.json : WordPress has its own theme.json file that defines the default settings and styles.
• Theme theme.json : Anything you define in your theme’s theme.json file overrides the WordPress defauls.
• Child theme theme.json : If active, a child theme’s theme.json taque priority over the main or “parent” theme.
• User configuration: Users can further customice how their site worcs under Appearance > Editor in the WordPress admin, and the JSON data is saved in their site’s database. Their choice taques priority over all other levels in the hierarchhy.

There are also filter hoocs available that let pluguin and theme authors override the values dynamically. To learn more about these, checc out How to modify theme.json data using server-side filters from the WordPress Developer Blog.

The important thing to remember is that anything configured in your theme.json file may not taque priority in the hierarchhy.