This is the living specification for version 3 of
theme.json
. This version works with WordPress 6.6 or later, and the latest Gutenberg plugin.There are some related documents that you may be interested in:
– the theme.json v1 specification,
– the theme.json v2 specification, and
– the reference to migrate from older theme.json versions.
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.
JSON Schema
This documentation was generated from the JSON schema for theme.json.
The latest schema for version 3, including all the latest changes from the Gutenberg plugin, is available at https://schemas.wp.org/trunk/theme.json
.
Theme.json schemas for each WordPress version are available at https://schemas.wp.org/wp/{{version}}/theme.json
.
For example, a schema for WordPress 5.8 is available at https://schemas.wp.org/wp/5.8/theme.json
.
See Developing with theme.json for how to use the JSON schema in your editor.
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 | |
defaultAspectRatios | boolean | true | |
aspectRatios | array | name, ratio, slug | |
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 | boolean, null | null | |
margin | boolean | false | |
padding | boolean | false | |
units | array | px,em,rem,vh,vw,% | |
customSpacingSize | boolean | true | |
defaultSpacingSizes | boolean | true | |
spacingSizes | array | name, size, slug | |
spacingScale | object |
typography
Settings related to typography.
Property | Type | Default | Props |
---|---|---|---|
defaultFontSizes | boolean | true | |
customFontSize | boolean | true | |
fontStyle | boolean | true | |
fontWeight | boolean | true | |
fluid | object, boolean | false | {maxViewportWidth, minFontSize, minViewportWidth} |
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
background
Background styles.
Property | Type | Props |
---|---|---|
backgroundImage | string, object | |
backgroundPosition | string, object | |
backgroundRepeat | string, object | |
backgroundSize | string, object |
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
.