This is the living specification for version 2 of
theme.json. This version works with WordPress 5.9 or later, and the latest Gutenberg plugin.There are some related documents that you may be interested in:
– the theme.json v1 specification, and
– the reference to migrate from theme.json v1 to v2.
This reference guide lists the settings and style properties defined in the theme.json schema. See the theme.json how to guide for examples and guidance on how to use the theme.json file in your theme.
Schema
Remembering the theme.json settings and properties while you develop can be difficult, so a JSON schema was created to help.
Code editors can pick up the schema and can provide helpful hints and suggestions such as tooltips, autocomplete, or schema validation in the editor. To use the schema in Visual Studio Code, add $schema: “https://schemas.wp.org/trunk/theme.json” to the beginning of your theme.json file together with a version corresponding to the version you wish to use, e.g.:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
...
}
Settings
appearanceTools
Setting that enables the following UI tools:
- background: backgroundImage, backgroundSize
- border: color, radius, style, width
- color: link, heading, button, caption
- dimensions: aspectRatio, minHeight
- position: sticky
- spacing: blockGap, margin, padding
- typography: lineHeight
useRootPaddingAwareAlignments
Note: Since WordPress 6.1.
Enables root padding (the values from styles.spacing.padding) to be applied to the contents of full-width blocks instead of the root block.
Please note that when using this setting, styles.spacing.padding should always be set as an object with top, right, bottom, left values declared separately.
border
Settings related to borders.
| Property | Type | Default | Props |
|---|---|---|---|
| color | boolean | false | |
| radius | boolean | false | |
| style | boolean | false | |
| width | boolean | false |
shadow
Settings related to shadows.
| Property | Type | Default | Props |
|---|---|---|---|
| defaultPresets | boolean | true | |
| presets | array | name, shadow, slug |
color
Settings related to colors.
| Property | Type | Default | Props |
|---|---|---|---|
| background | boolean | true | |
| custom | boolean | true | |
| customDuotone | boolean | true | |
| customGradient | boolean | true | |
| defaultDuotone | boolean | true | |
| defaultGradients | boolean | true | |
| defaultPalette | boolean | true | |
| duotone | array | colors, name, slug | |
| gradients | array | gradient, name, slug | |
| link | boolean | false | |
| palette | array | color, name, slug | |
| text | boolean | true | |
| heading | boolean | true | |
| button | boolean | true | |
| caption | boolean | true |
background
Settings related to background.
| Property | Type | Default | Props |
|---|---|---|---|
| backgroundImage | boolean | false | |
| backgroundSize | boolean | false |
dimensions
Settings related to dimensions.
| Property | Type | Default | Props |
|---|---|---|---|
| aspectRatio | boolean | false | |
| minHeight | boolean | false |
layout
Settings related to layout.
| Property | Type | Default | Props |
|---|---|---|---|
| contentSize | string | ||
| wideSize | string | ||
| allowEditing | boolean | true | |
| allowCustomContentAndWideSize | boolean | true |
lightbox
Settings related to the lightbox.
| Property | Type | Default | Props |
|---|---|---|---|
| enabled | boolean | ||
| allowEditing | boolean |
position
Settings related to position.
| Property | Type | Default | Props |
|---|---|---|---|
| sticky | boolean | false |
spacing
Settings related to spacing.
| Property | Type | Default | Props |
|---|---|---|---|
| blockGap | undefined | null | |
| margin | boolean | false | |
| padding | boolean | false | |
| units | array | px,em,rem,vh,vw,% | |
| customSpacingSize | boolean | true | |
| spacingSizes | array | name, size, slug | |
| spacingScale | object |
typography
Settings related to typography.
| Property | Type | Default | Props |
|---|---|---|---|
| customFontSize | boolean | true | |
| fontStyle | boolean | true | |
| fontWeight | boolean | true | |
| fluid | undefined | false | |
| letterSpacing | boolean | true | |
| lineHeight | boolean | false | |
| textAlign | boolean | true | |
| textColumns | boolean | false | |
| textDecoration | boolean | true | |
| writingMode | boolean | false | |
| textTransform | boolean | true | |
| dropCap | boolean | true | |
| fontSizes | array | fluid, name, size, slug | |
| fontFamilies | array | fontFace, fontFamily, name, 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.
Styles
border
Border styles.
| Property | Type | Props |
|---|---|---|
| color | string, object | |
| radius | string, object | |
| style | string, object | |
| width | string, object | |
| top | object | color, style, width |
| right | object | color, style, width |
| bottom | object | color, style, width |
| left | object | color, style, width |
color
Color styles.
| Property | Type | Props |
|---|---|---|
| background | string, object | |
| gradient | string, object | |
| text | string, object |
dimensions
Dimensions styles
| Property | Type | Props |
|---|---|---|
| aspectRatio | string, object | |
| minHeight | string, object |
spacing
Spacing styles.
| Property | Type | Props |
|---|---|---|
| blockGap | string, object | |
| margin | object | bottom, left, right, top |
| padding | object | bottom, left, right, top |
typography
Typography styles.
| Property | Type | Props |
|---|---|---|
| fontFamily | string, object | |
| fontSize | string, object | |
| fontStyle | string, object | |
| fontWeight | string, object | |
| letterSpacing | string, object | |
| lineHeight | string, object | |
| textAlign | string | |
| textColumns | string | |
| textDecoration | string, object | |
| writingMode | string, object | |
| textTransform | string, object |
filter
CSS and SVG filter styles.
| Property | Type | Props |
|---|---|---|
| duotone | string, object |
shadow
Box shadow styles.
outline
Outline styles.
| Property | Type | Props |
|---|---|---|
| color | string, object | |
| offset | string, object | |
| style | string, object | |
| width | string, object |
css
Sets custom CSS to apply styling not covered by other theme.json properties.
customTemplates
Additional metadata for custom templates defined in the templates folder.
Type: object.
| Property | Description | Type |
|---|---|---|
| name | Filename, without extension, of the template in the templates folder. | string |
| title | Title of the template, translatable. | string |
| postTypes | List of post types that can use this custom template. | array |
templateParts
Additional metadata for template parts defined in the parts folder.
Type: object.
| Property | Description | Type |
|---|---|---|
| name | Filename, without extension, of the template in the parts folder. | string |
| title | Title of the template, translatable. | string |
| area | The area the template part is used for. Block variations for header and footer values exist and will be used when the area is set to one of those. |
string |
Patterns
An array of pattern slugs to be registered from the Pattern Directory.
Type: array.