Theme.json Version 2 Reference

This is the specification for version 2 of theme.json. This version works with WordPress 5.9 or later.

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 last schema for version 2 is available at `https://schemas.wp.org/wp/6.5/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.9 is available athttps://schemas.wp.org/wp/5.9/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
• dimensions: aspectRatio, minHeight
• position: sticky
• spacing: blockGap, margin, padding
• typography: lineHeight

---

useRootPaddingAwareAlignments

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

---

background

Settings related to background.

Property	Type	Default	Props
backgroundImage	boolean	false

---

dimensions

Settings related to dimensions.

Property	Type	Default	Props
aspectRatio	boolean	false
minHeight	boolean	false

---

layout

Settings related to layout.

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

---

lightbox

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

---

typography

Settings related to typography.

Property	Type	Default	Props
customFontSize	boolean	true
fontStyle	boolean	true
fontWeight	boolean	true
fluid	object, boolean	false	{maxViewportWidth, minFontSize, minViewportWidth}
letterSpacing	boolean	true
lineHeight	boolean	false
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
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.