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.

Top ↑

Settings

Top ↑

appearanceTools

Setting that enables the following UI tools:

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

Top ↑

border

Settings related to borders.

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

Top ↑

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

Top ↑

layout

Settings related to layout.

Property Type Default Props
contentSize string
wideSize string

Top ↑

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

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

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

Top ↑

border

Border styles.

Property Type Props
color string
radius undefined
style string
width string
top undefined
right undefined
bottom undefined
left undefined

Top ↑

color

Color styles.

Property Type Props
background string
gradient string
text string

Top ↑

spacing

Spacing styles.

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

Top ↑

typography

Typography styles.

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