Version 2 (living reference) Edit

This is the living specification for the version 2 of theme.json. This version works with the upcoming WordPress 5.9 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.

Settings Settings

Top ↑

appearanceTools appearanceTools

Setting that enables the following UI tools:

  • border: color, radius, style, width
  • color: link
  • spacing: blockGap, margin, padding
  • typography: lineHeight

Top ↑

border border

Settings related to borders.

Property Type Default Props
color boolean false
radius boolean false
style boolean false
width boolean false

Top ↑

color color

Settings related to colors.

Property Type Default Props
background boolean true
custom boolean true
customDuotone boolean true
customGradient 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

Top ↑

layout layout

Settings related to layout.

Property Type Default Props
contentSize string
wideSize string

Top ↑

spacing 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,%

Top ↑

typography 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

Top ↑

custom 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.


Top ↑

Styles Styles

Top ↑

border border

Border styles.

Property Type Props
color string
radius string
style string
width string

Top ↑

color color

Color styles.

Property Type Props
background string
gradient string
text string

Top ↑

spacing spacing

Spacing styles.

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

Top ↑

typography typography

Typography styles.

Property Type Props
fontFamily string
fontSize string
fontStyle string
fontWeight string
letterSpacing string
lineHeight string
textDecoration string
textTransform string