Theme.json version 3

The theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. version is incremented whenever a breaking change would need to be made to the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.. This allows consumers to opt-in to the breaking change by updating the version. Older theme.json versions will always be supported in the latest versions of WordPress.

Updating to version 3 is recommended when your minimum supported WordPress version reaches 6.6. See theme.json version 3 frequently asked questions for more information on when to update. Then check out the theme.json reference for migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. instructions when you are ready to update.

Breaking changes in version 3

Starting with theme.json version 3 the default behavior for using the same slugs as the default fontSizes and spacingSizes presets has been changed to match how other theme.json presets work: from always overriding the default presets to requiring defaultFontSizes or defaultSpacingSizes to be false in order to override the default presets.

Default font sizes

settings.typography.defaultFontSizes is a new option in theme.json v3. It controls whether the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. provided default settings.typography.fontSizes presets are shown and used.

The default fontSizes presets’ slugs are: small, medium, large, and x-large.

• When defaultFontSizes is true it will show the default font sizes in the editor and prevent the theme from creating presets using the default slugs.
• When defaultFontSizes is false it will hide the default font sizes in the editor and allow the theme to use the default slugs.

For blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. themes defaultFontSizes is true by default. This is consistent with how other default* options work such as settings.color.defaultPalette.

In theme.json v2, the default font sizes were only shown when theme sizes were not defined. A theme providing font sizes with the same slugs as the defaults would always override the defaults.

To keep behavior similar to v2 with a v3 theme.json:

• If you do not have any fontSizes defined, defaultFontSizes can be left out or set to true.
• If you have some fontSizes defined, set defaultFontSizes to false.

--- theme.json v2
+++ theme.json v3
@@ -1,24 +1,25 @@
 {
-	"version": 2,
+	"version": 3,
 	"settings": {
 		"typography": {
+			"defaultFontSizes": false,
 			"fontSizes": [
 				{
 					"name": "Small",
 					"slug": "small",
 					"size": "10px"
 				},
 				{
 					"name": "Medium",
 					"slug": "medium",
 					"size": "14px"
 				},
 				{
 					"name": "Large",
 					"slug": "large",
 					"size": "20px"
 				}
 			]
 		}
 	}
 }

Default spacing sizes

settings.spacing.defaultSpacingSizes is a new option in theme.json v3. It controls whether the core provided default settings.spacing.spacingSizes presets are shown and used.

The default spacingSizes presets’ slugs are: 20, 30, 40, 50, 60, 70, and 80.

• When defaultSpacingSizes is true it will show the default spacing sizes in the editor and prevent the theme from creating presets using the default slugs.
• When defaultSpacingSizes is false it will hide the default spacing sizes in the editor and allow the theme to use the default slugs.

defaultSpacingSizes is true by default. This is consistent with how other default* options work such as settings.color.defaultPalette.

In theme.json v2, the default spacing sizes were only shown when theme sizes were not defined. A theme providing spacing sizes with the same slugs as the defaults would always override the defaults.

Furthermore, there are two settings that can be used to set theme level spacing sizes: spacingSizes and spacingScale. With theme.json v3, presets from both will be merged together and sorted numerically by slug. Presets defined in spacingSizes will override those generated by spacingScale if the slugs match.

In theme.json v2, setting both spacingSizes and spacingScale would only use the values from spacingSizes.

To keep behavior similar to v2 with a v3 theme.json:

• If you do not have any spacingSizes presets or spacingScale config defined, defaultSpacingSizes can be left out or set to true.
• If you disabled default spacing sizes by setting spacingScale to { "steps": 0 }, remove the spacingScale config and set defaultSpacingSizes to false.
• If you defined only one of either spacingScale or spacingSizes for your presets, set defaultSpacingSizes to false.
• If you defined both spacingScale and spacingSizes, remove the spacingSizes config and set defaultSpacingSizes to false.

--- theme.json v2
+++ theme.json v3
@@ -1,27 +1,25 @@
 {
-	"version": 2,
+	"version": 3,
 	"settings": {
 		"spacing": {
-			"spacingScale": {
-				"steps": 0
-			},
+			"defaultSpacingSizes": false,
 			"spacingSizes": [
 				{
 					"name": "Small",
 					"slug": "40",
 					"size": "1rem"
 				},
 				{
 					"name": "Medium",
 					"slug": "50",
 					"size": "1.5rem"
 				},
 				{
 					"name": "Large",
 					"slug": "60",
 					"size": "2rem"
 				}
 			]
 		}
 	}
 }

Props to @scruffian and @juanmaguitar for assistance with writing and reviewing this post.

#6-6, #dev-note, #dev-notes, #dev-notes-6-6