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 ↑

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.


Top ↑

border

Settings related to borders.

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

Top ↑

shadow

Settings related to shadows.

Property Type Default Props
presets array name, shadow, slug

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 ↑

dimensions

Settings related to dimensions.

Property Type Default Props
minHeight boolean false

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,%
customSpacingSize boolean true
spacingSizes array name, size, slug
spacingScale object

Top ↑

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

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

Top ↑

color

Color styles.

Property Type Props
background string, object
gradient string, object
text string, object

Top ↑

spacing

Spacing styles.

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

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

Top ↑

filter

CSS and SVG filter styles.

Property Type Props
duotone string, object

Top ↑

shadow

Box shadow styles.


Top ↑

outline

Outline styles.

Property Type Props
color string, object
offset string, object
style string, object
width string, object

Top ↑

css

Sets custom CSS to apply styling not covered by other theme.json properties.