Table of Contents
WordPress’s Gutenberg editor has revolutionized the way themes are created and customized, and at the heart of this transformation is the theme.json file. This file acts as a central configuration hub for a theme, defining its settings, styles, and structural elements. Let’s dive into an example theme.json file to understand its various components and how they shape a WordPress theme.
Most of the settings below can now be easily adjusted via Global Styles, making theme customization simpler and more user-friendly, even for those with limited technical skills. With Global Styles in block themes, you can change typography, color schemes, layout sizes, and block styles.
Here is a breakdown of the Twenty Twenty Four WordPress Theme.json file.
$schema and version
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"patterns": [
"three-columns-of-services",
"clients-section"
],
The $schema key specifies the URL to the JSON schema definition for theme.json, ensuring the structure of the file is valid. The version key denotes the version of the theme.json specification the theme is using. In this case, it’s version 2.
patterns
This section lists the block patterns included in the theme. Block patterns are predefined block layouts, making it easier for users to create complex layouts. Here, three-columns-of-services and clients-section are custom patterns defined by the theme.
: [
"three-columns-of-services",
"clients-section"
],settings
"settings": {
"appearanceTools": true,The settings section is where the global settings of the theme are defined. These settings can be anything from color palettes to typography and layout configurations. In our example, appearanceTools is set to true, enabling additional appearance tools in the editor.
color
"color": {
"defaultDuotone": false,
"defaultPalette": false,
"defaultGradients": false,
Under settings, the color object controls various aspects of color settings in the theme. We see options like defaultDuotone, defaultPalette, and defaultGradients set to false, indicating that the theme opts out of the default color settings of WordPress and instead will provide its own.
duotone
"duotone": [
{
"colors": ["#111111", "#ffffff"],
"slug": "duotone-1",
"name": "Black and white"
},
// ... Additional duotone colors
],
This is an array of duotone color presets. Each duotone preset is an object with colors, slug, and name. These presets define two-color gradients that can be applied to images and other elements in the theme.
gradients
"gradients": [
{
"slug": "gradient-1",
"gradient": "linear-gradient(to bottom, #cfcabe 0%, #F9F9F9 100%)",
"name": "Vertical soft beige to white"
},
// ... Additional gradient colors
],This section defines a list of custom gradient presets. Each gradient is an object with a slug, gradient (the actual CSS gradient definition), and a name.
palette
Here, we define a custom color palette for the theme. Each color in the palette is an object containing color, name, and slug.
"palette": [
{
"color": "#f9f9f9",
"name": "Base",
"slug": "base"
},
// ... Additional color palette entries
]
},layout
"layout": {
"contentSize": "620px",
"wideSize": "1280px"
},
The layout object specifies the default sizes for the content area. contentSize is the default width for the content area, and wideSize is the width for wide alignments.
spacing
This section defines the global spacing settings for the theme. It includes a spacingScale and an array of spacingSizes, which are used to set consistent spacing throughout the theme.
"spacing": {
"spacingScale": {
"steps": 0
},
"spacingSizes": [
{
"name": "1",
"size": "1rem",
"slug": "10"
},
// ... Additional spacing sizes
],typography
In the typography object, we find settings related to fonts. This includes options like fluid for fluid typography, and fontFamilies, which is an array defining the fonts used in the theme. Each font family object can include fontFace definitions for custom font loading.
"typography": {
"fluid": true,
"fontFamilies": [
{
"fontFace": [
{
"fontFamily": "Inter",
// ... Font face details
}
],
"fontFamily": "\"Inter\", sans-serif",
"name": "Inter",
"slug": "body"
},
// ... Additional font families
],fontSizes
This is an array of font size presets. Each font size is an object with properties like fluid, name, size, and slug.
"fontSizes": [
{
"fluid": false,
"name": "Small",
"size": "0.9rem",
"slug": "small"
},
// ... Additional font sizes
],
"writingMode": true
},writingMode
Enables the writing mode in the theme, allowing for vertical text.
useRootPaddingAwareAlignments
"useRootPaddingAwareAlignments": true
},This setting, when true, enables alignment options that are aware of the root padding settings of the theme.
styles
The styles section is where you define default styles for various elements and blocks in the theme. For example, here we see a style defined for the core/avatar block, setting a border radius.
"styles": {
"blocks": {
"core/avatar": {
"border": {
"radius": "90px"
}
},
// ... Styles for additional blocks
},color
This subsection under styles defines the default background and text colors using the custom color variables set in the palette.
"color": {
"background": "var(--wp--preset--color--base)",
"text": "var(--wp--preset--color--contrast)"
},
// ... Additional global styles
},templateParts
This section lists the template parts (like headers, footers, sidebars) used in the theme. Each part is an object with area, name, and title.
"templateParts": [
{
"area": "header",
"name": "header",
"title": "Header"
},
// ... Additional template parts
],customTemplates
Finally, the customTemplates array defines custom templates available in the theme. Each template is an object with name, postTypes, and title.
"customTemplates": [
{
"name": "page-no-title",
"postTypes": ["page"],
"title": "Page No Title"
},
// ... Additional custom templates
]}Locking things down with theme.json
You can disable various features by setting their corresponding flags to false or by omitting certain features. Here are some common settings you might want to disable:
Color Settings: To disable custom colors, gradients, or the color picker:
“settings”: {
“color”: {
“custom”: false, // Disables custom color picker
“customGradient”: false, // Disables custom gradient picker
“gradients”: [], // Disables gradient presets
“palette”: [] // Disables color palette presets
}
}
Typography Settings: To turn off custom font sizes or custom line heights:
“settings”: {
“typography”: {
“customFontSize”: false, // Disables custom font sizes
“customLineHeight”: false // Disables custom line heights
}
}
Block-Specific Settings: To disable features on specific blocks, like disabling the button block’s custom padding:
“settings”: {
“blocks”: {
“core/button”: {
“spacing”: {
“padding”: false
}
}
}
}
Layout and Spacing: To disable custom spacing or layout settings:
“settings”: {
“spacing”: {
“customPadding”: false, // Disables custom padding control
“units”: [] // Disables specific units like ’em’, ‘rem’, ‘%’, etc.
},
“layout”: {
“contentSize”: [],
“wideSize”: []
}
}
After making the changes, save the theme.json file. If you’re working on a local environment, the changes will take effect immediately. If you’re working on a remote server, you’ll need to upload the modified theme.json file to your theme directory on the server.
Go to the WordPress editor and create or edit a post or a page. You should see that the disabled settings are no longer available in the editor. Some settings may have fallbacks or default values that the theme will revert to if you disable custom options.
Conclusion
This walkthrough of the theme.json file highlights its role as a comprehensive configuration file for WordPress themes, especially those using the Gutenberg editor. By controlling settings, styles, and structural elements, it provides a powerful way to shape the look and feel of a theme.
Leave a Reply