If you work with the block editor, you have heard about the theme.json file, which allows WordPress theme developers to define and apply theme settings to various theme elements.
Introduced in WordPress 5.8, the theme.json file provides developers with control over the settings and styles of blocks in the editor. As the site editing experience has evolved to include blocks, the range of settings requiring management has expanded. The theme.json file centralizes these configurations, ensuring a consistent experience when applying theme settings and styles.
The theme.json file, located in the root directory of a WordPress theme, contains a JSON object consisting of key-value pairs. JSON (JavaScript Object Notation) is a standard format for representing structured data. The main JSON object is enclosed in curly braces, and each key-value pair is separated by a comma, which is essential except for the last pair in an object. A good code editor will highlight errors if commas are missing.
Schema validation in theme.json enables auto-completion in code editors, suggesting available options and values. To enable this, add the schema key and its value at the top of the file, available in the Block Editor handbook. This feature helps ensure correct syntax and provides descriptions of each option.
WordPress Core includes a default theme.json, which sets specific settings and predefined CSS variables. The settings key allows developers to extend or modify these settings and functionality. For example, enabling appearanceTools (disabled by default) allows control over border color, radius, style, width, link color, block gap, margin, padding, and text line height.
Replacing the add_theme_support requirements in the functions.php file, theme.json allows for defining custom colors directly within the JSON configuration. For instance, disabling custom colors globally can be achieved by setting settings.color.custom to false. Custom colors for specific blocks can also be enabled as needed.
Additionally, new CSS preset variables can be defined within theme.json. For example, to add a new colour to the palette, specify its name, hex value, and slug under the settings.color.palette key. These colours become available throughout the theme and can be applied globally or to specific blocks or elements.
For a comprehensive understanding of theme.json capabilities, refer to the Global Settings and Styles guide, the theme.json reference in the Block Editor handbook, and the Theme handbook.
Jane James is the founder of Alpha Omega Digital, and is a WordPress web developer based in Melbourne, Australia but also services clients from Sydney, Brisbane, Newcastle, Perth, Adelaide, Darwin and Hobart. Have a project in mind? Contact me here.