Theme.json Version 1 Reference

This is the specification for version 1 of theme.json. This version works with WordPress 5.8 or later.

Theme.json version 2 has been released with WordPress 5.9. WordPress will continue to support theme.json version 1. However new features will only be added to [new versions](

When you are ready to upgrade, see the [theme.json migration guide]( 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

The last schema for version 1 is available at ``.

Theme.json schemas for each WordPress version are available at{{version}}/theme.json`. For example a schema for WordPress 5.8 is available at`.

See Developing with theme.json for how to use the JSON schema in your editor.



Settings related to borders.

Property Type Default Props
customRadius boolean false


Settings related to colors.

Property Type Default Props
custom boolean true
customDuotone boolean true
customGradient boolean true
duotone array colors, name, slug
gradients array gradient, name, slug
link boolean false
palette array color, name, slug


Settings related to layout.

Property Type Default Props
contentSize string
wideSize string


Settings related to spacing.

Property Type Default Props
customMargin boolean false
customPadding boolean false
units array px,em,rem,vh,vw,%


Settings related to typography.

Property Type Default Props
customFontSize boolean true
customLineHeight boolean false
dropCap boolean true
fontSizes array name, size, slug


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.



Border styles.

Property Type Props
radius string


Color styles.

Property Type Props
background string
gradient string
text string


Spacing styles.

Property Type Props
margin object bottom, left, right, top
padding object bottom, left, right, top


Typography styles.

Property Type Props
fontSize string
lineHeight string