This is the specification for version 2 of
theme.json. This version works with WordPress 5.9 or later.
Theme.json version 3 has been released with WordPress 6.6. WordPress will continue to support theme.json version 2. However new features will only be added to [new versions](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/).
When you are ready to upgrade, see the [theme.json migration guide](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-migrations/#migrating-from-v2-to-v3) for details on updating to the latest version.
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 last schema for version 2 is available at `https://schemas.wp.org/wp/6.5/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.9 is available athttps://schemas.wp.org/wp/5.9/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
- dimensions: aspectRatio, minHeight
- position: sticky
- spacing: blockGap, margin, padding
- typography: lineHeight
useRootPaddingAwareAlignments
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 |
background
Settings related to background.
| Property | Type | Default | Props |
|---|---|---|---|
| backgroundImage | 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 | boolean, null | 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 | object, boolean | false | {maxViewportWidth, minFontSize, minViewportWidth} |
| letterSpacing | boolean | true | |
| lineHeight | boolean | false | |
| 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 | |
| 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.