Version 2 (living reference) 
Edit
This is the living specification for the version 2 of theme.json. This version works with WordPress 5.9 or later, and the latest Gutenberg plugin.
There’re related documents 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 guide on how to use the theme.json file in your theme.
Schema
It can be difficult to remember the theme.json settings and properties while you develop, so a JSON scheme was created to help. The schema is available at https://schemas.wp.org/trunk/theme.json
Code editors can pick up the schema and can provide help like 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.
Settings
appearanceTools
Setting that enables the following UI tools:
- border: color, radius, style, width
- color: link
- 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 |
|---|---|---|---|
| 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 |
dimensions
Settings related to dimensions.
| Property | Type | Default | Props |
|---|---|---|---|
| minHeight | boolean | false |
layout
Settings related to layout.
| Property | Type | Default | Props |
|---|---|---|---|
| contentSize | string | ||
| wideSize | string |
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 | |
| textDecoration | boolean | true | |
| 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 |
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 | |
| textDecoration | 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.