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
border
Settings related to borders.
| Property | Type | Default | Props |
|---|---|---|---|
| color | boolean | false | |
| radius | boolean | false | |
| style | boolean | false | |
| width | boolean | false |
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 |
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,% |
typography
Settings related to typography.
| Property | Type | Default | Props |
|---|---|---|---|
| customFontSize | boolean | true | |
| fontStyle | boolean | true | |
| fontWeight | boolean | true | |
| letterSpacing | boolean | true | |
| lineHeight | boolean | false | |
| textDecoration | boolean | true | |
| textTransform | boolean | true | |
| dropCap | boolean | true | |
| fontSizes | array | name, size, slug | |
| fontFamilies | array | 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 | |
| radius | undefined | |
| style | string | |
| width | string | |
| top | undefined | |
| right | undefined | |
| bottom | undefined | |
| left | undefined |
color
Color styles.
| Property | Type | Props |
|---|---|---|
| background | string | |
| gradient | string | |
| text | string |
spacing
Spacing styles.
| Property | Type | Props |
|---|---|---|
| blockGap | string | |
| margin | object | bottom, left, right, top |
| padding | object | bottom, left, right, top |
typography
Typography styles.
| Property | Type | Props |
|---|---|---|
| fontFamily | string | |
| fontSize | string | |
| fontStyle | string | |
| fontWeight | string | |
| letterSpacing | string | |
| lineHeight | string | |
| textDecoration | string | |
| textTransform | string |