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
Settings for the block editor and individual blocks. These include things like:
– Which customization options should be available to the user.
– The default colors, font sizes… available to the user.
– CSS custom properties and class names used in styles.
– And the default layout of the editor (widths and available alignments).
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.
Note: Top-level only property. Not available in blocks.
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
background
Settings related to background.
| Property | Description | Type | Default |
|---|---|---|---|
| backgroundImage | Allow users to set a background image. | boolean |
false |
| backgroundSize | Allow users to set values related to the size of a background image, including size, position, and repeat controls. | boolean |
false |
border
Settings related to borders.
| Property | Description | Type | Default |
|---|---|---|---|
| color | Allow users to set custom border colors. | boolean |
false |
| radius | Allow users to set custom border radius. | boolean |
false |
| style | Allow users to set custom border styles. | boolean |
false |
| width | Allow users to set custom border widths. | boolean |
false |
color
Settings related to colors.
| Property | Description | Type | Default |
|---|---|---|---|
| background | Allow users to set background colors. | boolean |
true |
| custom | Allow users to select custom colors. | boolean |
true |
| customDuotone | Allow users to create custom duotone filters. | boolean |
true |
| customGradient | Allow users to create custom gradients. | boolean |
true |
| defaultDuotone | Allow users to choose filters from the default duotone filter presets. | boolean |
true |
| defaultGradients | Allow users to choose colors from the default gradients. | boolean |
true |
| defaultPalette | Allow users to choose colors from the default palette. | boolean |
true |
| duotone | Duotone presets for the duotone picker. | [ { name, slug, colors } ] |
|
| gradients | Gradient presets for the gradient picker. | [ { name, slug, gradient } ] |
|
| link | Allow users to set link colors in a block. | boolean |
false |
| palette | Color palette presets for the color picker. | [ { name, slug, color } ] |
|
| text | Allow users to set text colors in a block. | boolean |
true |
| heading | Allow users to set heading colors in a block. | boolean |
true |
| button | Allow users to set button colors in a block. | boolean |
true |
| caption | Allow users to set caption colors in a block. | boolean |
true |
dimensions
Settings related to dimensions.
| Property | Description | Type | Default |
|---|---|---|---|
| aspectRatio | Allow users to set an aspect ratio. | boolean |
false |
| defaultAspectRatios | Allow users to choose aspect ratios from the default set of aspect ratios. | boolean |
true |
| aspectRatios | Allow users to define aspect ratios for some blocks. | [ { name, slug, ratio } ] |
|
| minHeight | Allow users to set custom minimum height. | boolean |
false |
layout
Settings related to layout.
| Property | Description | Type | Default |
|---|---|---|---|
| contentSize | Sets the max-width of the content. | string |
|
| wideSize | Sets the max-width of wide (.alignwide) content. Also used as the maximum viewport when calculating fluid font sizes |
string |
|
| allowEditing | Disable the layout UI controls. | boolean |
true |
| allowCustomContentAndWideSize | Enable or disable the custom content and wide size controls. | boolean |
true |
lightbox
Settings related to the lightbox.
| Property | Description | Type | Default |
|---|---|---|---|
| enabled | Defines whether the lightbox is enabled or not. | boolean |
|
| allowEditing | Defines whether to show the Lightbox UI in the block editor. If set to false, the user won’t be able to change the lightbox settings in the block editor. |
boolean |
position
Settings related to position.
| Property | Description | Type | Default |
|---|---|---|---|
| sticky | Allow users to set sticky position. | boolean |
false |
shadow
Settings related to shadows.
| Property | Description | Type | Default |
|---|---|---|---|
| defaultPresets | Allow users to choose shadows from the default shadow presets. | boolean |
true |
| presets | Shadow presets for the shadow picker. | [ { name, slug, shadow } ] |
spacing
Settings related to spacing.
| Property | Description | Type | Default |
|---|---|---|---|
| blockGap | Enables --wp--style--block-gap to be generated from styles.spacing.blockGap. |
boolean, null |
null |
| margin | Allow users to set a custom margin. | boolean |
false |
| padding | Allow users to set a custom padding. | boolean |
false |
| units | List of units the user can use for spacing values. | [ string ] |
["px","em","rem","vh","vw","%"] |
| customSpacingSize | Allow users to set custom space sizes. | boolean |
true |
| defaultSpacingSizes | Allow users to choose space sizes from the default space size presets. | boolean |
true |
| spacingSizes | Space size presets for the space size selector. | [ { name, slug, size } ] |
|
| spacingScale | Settings to auto-generate space size presets for the space size selector. | { operator, increment, steps, mediumStep, unit } |
typography
Settings related to typography.
| Property | Description | Type | Default |
|---|---|---|---|
| defaultFontSizes | Allow users to choose font sizes from the default font size presets. | boolean |
true |
| customFontSize | Allow users to set custom font sizes. | boolean |
true |
| fontStyle | Allow users to set custom font styles. | boolean |
true |
| fontWeight | Allow users to set custom font weights. | boolean |
true |
| fluid | Enables fluid typography and allows users to set global fluid typography parameters. | boolean, { minFontSize, maxViewportWidth, minViewportWidth } |
false |
| letterSpacing | Allow users to set custom letter spacing. | boolean |
true |
| lineHeight | Allow users to set custom line height. | boolean |
false |
| textAlign | Allow users to set the text align. | boolean |
true |
| textColumns | Allow users to set the number of text columns. | boolean |
false |
| textDecoration | Allow users to set custom text decorations. | boolean |
true |
| writingMode | Allow users to set the writing mode. | boolean |
false |
| textTransform | Allow users to set custom text transforms. | boolean |
true |
| dropCap | Enable drop cap. | boolean |
true |
| fontSizes | Font size presets for the font size selector. | [ { name, slug, size, fluid } ] |
|
| fontFamilies | Font family presets for the font family selector. | [ { name, slug, fontFamily, fontFace } ] |
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
Organized way to set CSS properties. Styles in the top-level will be added in the body selector.
background
Background styles.
| Property | Description | Type |
|---|---|---|
| backgroundImage | Sets the background-image CSS property. |
string, { ref }, { url } |
| backgroundPosition | Sets the background-position CSS property. |
string, { ref } |
| backgroundRepeat | Sets the background-repeat CSS property. |
string, { ref } |
| backgroundSize | Sets the background-size CSS property. |
string, { ref } |
| backgroundAttachment | Sets the background-attachment CSS property. |
string, { ref } |
border
Border styles.
| Property | Description | Type |
|---|---|---|
| color | Sets the border-color CSS property. |
string, { ref } |
| radius | Sets the border-radius CSS property. |
string, { ref }, { topLeft, topRight, bottomLeft, bottomRight } |
| style | Sets the border-style CSS property. |
string, { ref } |
| width | Sets the border-width CSS property. |
string, { ref } |
| top | { color, style, width } |
|
| right | { color, style, width } |
|
| bottom | { color, style, width } |
|
| left | { color, style, width } |
color
Color styles.
| Property | Description | Type |
|---|---|---|
| background | Sets the background-color CSS property. |
string, { ref } |
| gradient | Sets the background CSS property. |
string, { ref } |
| text | Sets the color CSS property. |
string, { ref } |
css
Sets custom CSS to apply styling not covered by other theme.json properties.
dimensions
Dimensions styles.
| Property | Description | Type |
|---|---|---|
| aspectRatio | Sets the aspect-ratio CSS property. |
string, { ref } |
| minHeight | Sets the min-height CSS property. |
string, { ref } |
filter
CSS and SVG filter styles.
| Property | Description | Type |
|---|---|---|
| duotone | Sets the duotone filter. | string, { ref } |
outline
Outline styles.
| Property | Description | Type |
|---|---|---|
| color | Sets the outline-color CSS property. |
string, { ref } |
| offset | Sets the outline-offset CSS property. |
string, { ref } |
| style | Sets the outline-style CSS property. |
string, { ref } |
| width | Sets the outline-width CSS property. |
string, { ref } |
shadow
Box shadow styles.
spacing
Spacing styles.
| Property | Description | Type |
|---|---|---|
| blockGap | Sets the --wp--style--block-gap CSS custom property when settings.spacing.blockGap is true. |
string, { ref } |
| margin | Margin styles. | { top, right, bottom, left } |
| padding | Padding styles. | { top, right, bottom, left } |
typography
Typography styles.
| Property | Description | Type |
|---|---|---|
| fontFamily | Sets the font-family CSS property. |
string, { ref } |
| fontSize | Sets the font-size CSS property. |
string, { ref } |
| fontStyle | Sets the font-style CSS property. |
string, { ref } |
| fontWeight | Sets the font-weight CSS property. |
string, { ref } |
| letterSpacing | Sets the letter-spacing CSS property. |
string, { ref } |
| lineHeight | Sets the line-height CSS property. |
string, { ref } |
| textAlign | Sets the text-align CSS property. |
string, { ref } |
| textColumns | Sets the column-count CSS property. |
string, { ref } |
| textDecoration | Sets the text-decoration CSS property. |
string, { ref } |
| writingMode | Sets the writing-mode CSS property. |
string, { ref } |
| textTransform | Sets the text-transform CSS property. |
string, { ref } |
customTemplates
Additional metadata for custom templates defined in the templates folder.
| 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. | [ string ] |
templateParts
Additional metadata for template parts defined in the parts folder.
| 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: [ string ].