Theme.json Version 3 Reference (latest)

This is the living specification for version 3 of theme.json. This version works with WordPress 6.6 or later, and the latest Gutenberg plugin.

There are some related documents that you may be interested in:
– the theme.json v1 specification,
– the theme.json v2 specification, and
– the reference to migrate from older theme.json versions.

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

This documentation was generated from the JSON schema for theme.json.

The latest schema for version 3, including all the latest changes from the Gutenberg plugin, is available at https://schemas.wp.org/trunk/theme.json.

Theme.json schemas for each WordPress version are available at https://schemas.wp.org/wp/{{version}}/theme.json.
For example, a schema for WordPress 5.8 is available at https://schemas.wp.org/wp/5.8/theme.json.

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

Settings

appearanceTools

Setting that enables the following UI tools:

  • background: backgroundImage, backgroundSize
  • border: color, radius, style, width
  • color: link, heading, button, caption
  • dimensions: aspectRatio, minHeight
  • position: sticky
  • spacing: blockGap, margin, padding
  • typography: lineHeight

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.


border

Settings related to borders.

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

shadow

Settings related to shadows.

Property Type Default Props
defaultPresets boolean true
presets array name, shadow, slug

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
heading boolean true
button boolean true
caption boolean true

background

Settings related to background.

Property Type Default Props
backgroundImage boolean false
backgroundSize boolean false

dimensions

Settings related to dimensions.

Property Type Default Props
aspectRatio boolean false
defaultAspectRatios boolean true
aspectRatios array name, ratio, slug
minHeight boolean false

layout

Settings related to layout.

Property Type Default Props
contentSize string
wideSize string
allowEditing boolean true
allowCustomContentAndWideSize boolean true

Settings related to the lightbox.

Property Type Default Props
enabled boolean
allowEditing boolean

position

Settings related to position.

Property Type Default Props
sticky boolean false

spacing

Settings related to spacing.

Property Type Default Props
blockGap boolean, null null
margin boolean false
padding boolean false
units array px,em,rem,vh,vw,%
customSpacingSize boolean true
defaultSpacingSizes boolean true
spacingSizes array name, size, slug
spacingScale object

typography

Settings related to typography.

Property Type Default Props
defaultFontSizes boolean true
customFontSize boolean true
fontStyle boolean true
fontWeight boolean true
fluid object, boolean false {maxViewportWidth, minFontSize, minViewportWidth}
letterSpacing boolean true
lineHeight boolean false
textAlign boolean true
textColumns boolean false
textDecoration boolean true
writingMode boolean false
textTransform boolean true
dropCap boolean true
fontSizes array fluid, name, size, slug
fontFamilies array fontFace, 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, 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

color

Color styles.

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

dimensions

Dimensions styles

Property Type Props
aspectRatio string, object
minHeight string, object

spacing

Spacing styles.

Property Type Props
blockGap string, object
margin object bottom, left, right, top
padding object bottom, left, right, 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
textAlign string
textColumns string
textDecoration string, object
writingMode string, object
textTransform string, object

filter

CSS and SVG filter styles.

Property Type Props
duotone string, object

shadow

Box shadow styles.


outline

Outline styles.

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

css

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


customTemplates

Additional metadata for custom templates defined in the templates folder.

Type: object.

Property Description Type
name Filename, without extension, of the template in the templates folder. string
title Title of the template, translatable. string
postTypes List of post types that can use this custom template. array

templateParts

Additional metadata for template parts defined in the parts folder.

Type: object.

Property Description Type
name Filename, without extension, of the template in the parts folder. string
title Title of the template, translatable. string
area The area the template part is used for. Block variations for header and footer values exist and will be used when the area is set to one of those. string

Patterns

An array of pattern slugs to be registered from the Pattern Directory.
Type: array.