Theme.json
theme.json is a file that lives in the theme root directory of a theme and provides a canonical way to define many of the settings for the block editor including the following.
- What customization options should be made available or hidden from the user.
- What are the default colors, font sizes… available to the user.
- Defines the default layout of the editor (widths and available alignments).
How theme.json works in the child starter theme.
The theme.json file in the child-starter theme is actually compiled from several mjs files located in .../src/theme-json/. In order to affect changes in theme.json you’ll need to edit the following files.
config.mjssettings.mjsstyles.mjs
config.mjs
config.mjs houses core specifications for the theme.json file such as the theme.json version, as well as Custom Templates and Template part. It should look similar to the following in the child starter theme.
export default {
"version": 1,
"customTemplates": [ ],
"templateParts": [ ]
}“version”:
The version number sets what Theme Support features are available to use and the format. For WP5.8 this should always be set to 1, since version 2 was introduced in WP5.9, and version 3 in WP6.6.
For refnrece to the available propperties and and schema for version one visit https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-v1/
“customTemplates”: [ ]
This allows the declaration of custom templates present in the templates folder. For example, for a custom template named my-custom-template.html, the theme.json can declare what post types can use it and what’s the title to show the user
(not supported in WP5.8)
“templateParts”: [ ]
Whin this field themes can list the template parts present in the parts folder. For example, for a template part named my-template-part.html, the theme.json can declare the area term for the template part entity which is responsible for rendering the corresponding block variation (Header block, Footer block, etc.) in the editor.
(not supported in WP5.8)
settings.mjs
Settings covers a broad set of editor options and specifications that can be enabled/disabled or modified for a given theme. The following are available in version 1 (WP5.8).
border
Settings related to borders.
| Property | Type | Default | Props |
|---|---|---|---|
| customRadius | boolean | false |
color
Settings related to colors.
| Property | Type | Default | Props |
|---|---|---|---|
| custom | boolean | true | |
| customDuotone | boolean | true | |
| customGradient | boolean | true | |
| duotone | array | colors, name, slug | |
| gradients | array | gradient, name, slug | |
| link | boolean | false | |
| palette | array | color, name, slug |
layout
Settings related to layout.
| Property | Type | Default | Props |
|---|---|---|---|
| contentSize | string | ||
| wideSize | string |
spacing
Settings related to spacing.
| Property | Type | Default | Props |
|---|---|---|---|
| customMargin | boolean | false | |
| customPadding | boolean | false | |
| units | array | px,em,rem,vh,vw,% |
typography
Settings related to typography.
| Property | Type | Default | Props |
|---|---|---|---|
| customFontSize | boolean | true | |
| customLineHeight | boolean | false | |
| dropCap | boolean | true | |
| fontSizes | array | name, size, slug |
custom
Generate custom CSS custom properties of the form --wp--custom--{key}--{nested-key}: {value};. camelCased keys are transformed to kebab-case as to follow the CSS property naming schema. Keys at different depth levels are separated by --, so keys should not include -- in the name.
style.mjs
This file allows you to set style properties that are used globally for all blocks in the editor (top-level styles), as well as for specific blocks and block elements.
border
Border styles.
| Property | Type | Props |
|---|---|---|
| radius | string |
color
Color styles.
| Property | Type | Props |
|---|---|---|
| background | string | |
| gradient | string | |
| text | string |
spacing
Spacing styles.
| Property | Type | Props |
|---|---|---|
| margin | object | bottom, left, right, top |
| padding | object | bottom, left, right, top |
typography
Typography styles.
| Property | Type | Props |
|---|---|---|
| fontSize | string | |
| lineHeight | string |
More information can be found at https://developer.wordpress.org/block-editor/how-to-guides/themes/global-settings-and-styles/#styles
Using CSS Custom Properties
For many of these properties CSS Custom Properties (CSS Variables) can be used as opposed to fixed values. But it’s important to note that they must be used without spacing inside of the var() declaration, since this can cause errors in WordPresses style compilation process.
For example:"wideSize": "var(--bu-container-max-inline-size--wide)" will work fine but "wideSize": "var( --bu-container-max-inline-size--wide )" will not.
Additionally If you’re using Custom Properties that are carried over from editor-styles.css or theme.css and defined in those stylesheets, the admin settings panels will not inherently know the values for those Custom properties.
For example if you’ve defined "--theme-color-bu: #C00" in editor-style.css and use "var(--theme-color-bu)" as a color in settings.mjs, the color will show up in the bounds of the block editor and the block itself but not necessarily in the swatch for the the blocks color settings panel. to correct for this you’ll want to either define -theme-color-bu: #C00" in the admin.css sheet or use the variable with a fallback like so "color": "var(--theme-color-bu,#c00)"