-sidebar-toc>        -language-notice>

When you're developing a theme from scratch and modifying one you already have and implementing a new style, or working on the development of a child theme, understanding the basics of working using theme.json is essential.

This article aims to decode the primary and secondary (nested) properties of a theme.json file, focusing on the key styling and settings properties. These are the main elements of the file, and we'll give detailed explanations and code examples for each.

The foundation was laid in our previous article, , particularly in the last section .

What styles can be rendered using a block motif

WordPress uses the built-in cascading mechanism to display styles on websites. If multiple sources specify the same setting or style, WordPress must determine which style is the most important. Here is the precedence order that WordPress follows to decide the styles to be used:

1. WordPress Core --The fallback theme.json file is within the wp_includes directory. This file is updated with the latest WordPress releases and should not be modified.
2. Theme -- The primary theme.json file used by theme creators to set the settings of the theme, its style, and additional properties.
3. Style variants When a theme includes styles variations, each one has their individual theme.json file stored in the theme's subdirectory of styles.
4. Theme for children Similar to traditional themes, a child theme is able to modify the parent theme without altering its files (optional).
5. Theme style variations of children similar to the regular styles, a child theme can include its own theme.json file in its subdirectory for style (optional).
6. Styles created by users -- These are custom styles added through WordPress editors (for pages, posts or the site all in one) and stored inside the MySQL database.

The cascading sequence ensures that styles from higher-priority sources prevail over lower-priority sources. As an example, the settings within the theme's theme.json file will override the core WordPress theme.json. Likewise an individual theme's style variation will precede the parent theme's style variation.

User-created styles (6) have the top precedence, precluding other styles that are part of the cascade.

In this post we will focus at theme.json, the theme.json file located in the root directory of any WordPress blocks theme.

The reference to the primary properties as well as their value-added

Let's look at the top seven objects in theme.json, which we've grouped into three sections to make the information more comprehensible.

A few definitions prior to diving into

If you work in conjunction with theme.json, you will likely find varying definitions of important components. In order to make it clearer, let's look at how we define them in this article:

1. Sections Sections that are top-level options (also called "top-level objects" in some articles).
2. Objects-- The main components in the theme.json file, including setting and styles.
3. Properties -- The components in objects. In this case, for instance, the setting object is made up of 12 properties.
4. Key-value pair properties comprise key-value pairs. A "key" is the property's attribute, and it is enclosed by quotation marks. A "value" may be a boolean, string or array.

When we mention "by default," we refer to the default configurations in the core theme.json file, located at wp-includes/theme.json.

Syntax Overview

1. Booleans do not need to be included in quotation marks.
2. Strings are enclosed by double-quotes.
3. arrays are wrapped in round brackets [ Arrays are enclosed in brackets that contain [.
4. The objects are contained in curly braces {The object is enclosed in curly braces and contain many properties, or objects that are nested.
5. Commas are used to separate different key-value pairs inside an object.

Here's an example common syntax:

 "house":  "rooms": "kitchen"  

The grouping of properties

We've divided the property into three sections for easier navigation.

1. Basic properties
2. Properties of styles and settings
3. Patterns and templates properties

For simplicity, we've sometimes omitted the outer object wrappers. instead of discussing the complete arrangement:

 "settings":  "settings":  () "appearanceTools" false, "background":  "backgroundImage": true    

It could be shortened to:

"appearanceTools" False, "background":  "backgroundImage": true 

Basic properties

"$schema": "https://schemas.wp.org/wp/6.6/theme.json", "version": 3

Styles and Settings properties

If you're familiar with classic themes, consider the settings property as an option for features and functions usually stored in the theme's files and then displayed in the Appearance > Custom section of the WordPress administrator.

The Styles on the other hand, are similar to CSS properties that used to reside in the styles.css file, controlling the theme's layout and design.

Settings

Apart from the properties of the block or element properties, all other settings are globally. Because a lot of these settings are booleans, they act like toggles that allow or disallow an UI option.

It's important to note that not all keys apply to every situation. It's for instance impossible to permit users to define the minimum height of a paragraph block.

Appearance tools

These settings can be enabled separately or collectively through "appearanceTools": true.

Keys within appearanceTools are:

•      background
• backgroundImage lets the user to add an image background to blocks.
• backgroundSize is the way in which the background image is reduced in size (cover or contain. ).
•      border
• color -- Enables the color of borders.
• style allows the user select the border type (solid, dashed, dotted, etc. ).
• width controls the thickness of the border.
• radius lets users to set rounded corners by adjusting the border's radius.
•      Color
• link -- Enables setting the color of links in the text.
• heading -- Lets users define colors for heading tags (

,

, etc. ).

• button -- Controls the color of buttons used in the theme.
• caption allows setting the color of captions to be customized.
•      dimensions
• aspectRatio -- Lets users manage the ratio width to height of blocks.
• minHeight Allows the setting of a minimum height for blocks.
•      position
• sticky lets the user to create a sticky block, meaning it stays fixed on its place when scrolling.
•      spacing
• blockGap -- Controls block spacing.
• margin -- Lets users adjust the margins around the block.
• padding -- Manages the padding within an element, and defines the area between its content and its border.
•      typography
• lineHeight -- Allows users to change the height of lines (space between text lines) for improved reading.

Examples: If you want users to upload a background image while keeping the other tools for appearance off Use:

"appearanceTools": false, "background":  "backgroundImage": true 

Blocks

blocks property lets users enable specific settings for each block. block property permits users to set up settings for each block, which may override settings for the entire block.

Examples: If appearanceTools is set to false, but you still need to show borders for your block, use:

"border":  "color": true, "style": true, "width": true, "radius": true 

Color

This property lets users set color options for background colors as well as text colors, and gradients.

Keys that are part of the color property

• background -- Controls the background color of elements or components.
• customized -- Enables or disables the ability to allow users to choose custom colors.
• customDuotone allows people to create custom Duotone filters images.
• customGradient -- Enables custom gradient options.
• defaultDuotone -- Provides default duotone image filter options.
• defaultGradient -- Defines the default gradient options available to users.
• defaultPalette -- Sets the default color palette for the theme.
• duotone -- Allows duotone filters on images.
• gradient -- Enables gradients for backgrounds and other elements.
• hyperlink -- Sets the color of links within the theme.
• text -- Text color control.
• heading • Sets colours for headings (e.g., h1, h2, etc. ).
• button Controls button color options.
• caption -- Determines the color of captions to be used for multimedia elements.

Here are some instances:

Example 1. If you would like to disable the color picker feature for users, you can use these options:

"color":  "custom": false 

Example 2. For customizing primary theme color and secondary colors, it is possible to use this setup:

"color":  "palette": [  "slug": "primary", "color": "#0000ff", "name": "Primary" ,  "slug": "secondary", "color": "#ff0000", "name": "Secondary"  ] 

Dimensions

This property lets you manage the block's dimensions like size, width, height and aspect ratio.

Keys within the dimensions property

• aspectRatio allows users to define or block the aspect ratio of a block (e.g. 16:9, 4:3).
• defaultAspectRatios -- Defines default aspect ratios for blocks.
• minHeight allows the possibility of setting a minimum height for blocks.

For instance, to permit users to define an acceptable height for the blocks that are supported, you can use these steps:

"dimensions":  "minHeight": true 

Layout

Layout property Layout property allows users to define layout-related settings including the width of content and if users are able to modify the layout. Users can set layout options with these keys:

• ContentSize --Sets the default width of blocks.
• wideSize -The wideSize - Defines the block's width when the wide alignment option is chosen.
• permitEditing AllowEditingDetermines the extent to which users are able to alter layout options.
• allowCustomContentAndWideSize -- Enables the customization of contentSize and wideSize.

Example: Configure layout settings with default and wide block widths:

"layout":  "contentSize": "620px", "wideSize": "1000px" 

Lightbox

The lightbox property allows users to enable the "Expand when clicked" feature for images, opening them in a larger view when clicked.

Keys within the lightbox property:

• disabled -- Enables or disabling the feature of lightbox.
• allowEditing allows users to toggle the lightbox setting.

Example:To allow users to change the feature of lightbox for images, use this configuration:

"blocks""allowEditing"

Position

The property of position property lets users alter the positioning of blocks, for example placing a block in a sticky position to the page.

Example Create the block stick:

"position":  "sticky": true 

Shadow

This property lets users apply shadow effects to blocks, either by using the predefined templates or by creating custom-designed shadows.

Keys in the shadow property

• defaultPresets ---Enables or disables the default presets for shadows.
• presets --Allows users to define specific shadow pre-sets.

Here's an example in which the default shadows are disabled, and a custom shadow named "Natural" is defined as:

"shadow":  "defaultPresets": false, "presets": [  "name": "Natural", "slug": "natural", "shadow": "6px 6px 9px rgba(0, 0, 0, 0.2)"  ] 

The numbers represent the steps taken in the site editor in order to show the UI. The last step displays how to create the "Natural" shadow.

Spacing

This property defines the way that the spacing (padding margin gaps, margins) can be controlled by the editor.

Keys inside the space property

• blockGap controls the space between blocks.
• margin • Allows users to create margins around blocks.
• padding --Provides the option of setting padding within blocks.
• units --Defines the units that are available for spacing (e.g. (px and rem).
• customSpacingSize -ItAllows users to define custom spacing sizes.
• spacingSizes ---Defines the range of predefined spacing sizes.
• spacingScale --Allows the scaling of spacing units.

Example: To limit users to two measurements (pixels and rem) to determine margins, padding as well as widths and heights as well as to display the spacing controls in the editor for your site to set the appearanceTools in the appearanceTools section to the true setting and set it up as follows:

"spacing":  "units": ["px", "rem"] 

Typography

This setting controls setting of your theme's text, such as font size, weight, and line height.

Keys within the typography property:

• defaultFontSizes ---Defines the default font sizes accessible to the user.
• customFontSize -CustomFontSize -Enables or blocks the capability to set custom font sizes.
• fontStyle -ItControls the appearance of the font (e.g. italic, normal).
• fontWeight --Allows users to set the weight of the font (e.g. Bold and light, etc.).
• fluid ---Enables fluid typography. It adjusts the size of fonts dynamically according to screen size.
• letterSpacing (or )Controls how much space is left between letters.
• lineHeight --Sets the height of each paragraph of text.
• textAlign -- Allows control over text alignment (e.g., left, center, right).
• textDecoration textDecorationProvides alternatives for the decoration of text (e.g. underline).
• writingMode -The writingMode - Sets the writing mode for your text (e.g. vertical, horizontal or vertical).

Example For disabling both custom font sizes and ropCap options, use the following:

"typography":  "customFontSize": false, "dropCap": false 

In this situation, both of these selected keys won't never be displayed within the Editor.

Alignments that are aware of the root padding

If the property is set in true This property will ensure that full width or wide-width block alignments are aware of the padding applied to primary element on your webpage (e.g., or ) and ensures an even alignment when padding is applied.

    Example:    

"useRootPaddingAwareAlignments": true

If set to true When true, you should also determine the root's top, left, right and left paddings to be a style. (More details about the properties of style below).

"spacing":  "padding":  "top": "0", "right": "100px", "bottom": "0", "left": "100px"  

Applying the useRootPaddingAwareAlignements setting along with right and left padding to the body (as in the above code) results in the following.

Styles

The properties of the styles property enables you to apply CSS styles to your theme's base (default) particular elements, or even individual blocks within the theme.

Background style

You can control background-related properties like photos, positions, as well as attachments.

Common keys to back up:

• BackgroundImage --Defines the image used as background for the element or block.
• backgroundPosition --Sets the orientation of background images (e.g. the center, top-right).
• backgroundRepeat -The backgroundRepeat option Specifies the extent to which the background image is repeated (e.g. repeat, no-repeat).
• backgroundSize -(-)Controls the dimensions of the background image (e.g., cover or contain).
• backgroundAttachment -The valueSpecifies how the background picture stays fixed or scrolls with the page.

For example, you can choose a background picture for your theme:

"background":  "backgroundImage":  "url": "https://joyofwp.com/wp-content/uploads/2024/09/dots.png"  

Block specific styles

It is possible to apply certain styles including shadows, typography, and borders, to individual blocks.

Keys for border:

• colour -(-)Defines the color of the border.
• radius --Sets the border-radius for corner rounded edges.
• style CSS styleSpecifies the design that the border will have (e.g. solid, dots, etc.).
• size --Controls the width of border.
• Top, right, bottom, left Lets you define distinct border styles for each of the sides.

As an example, the following sets a 20px solid red border across the entire page

"border":  "color": "#ff0000", "width": "20px", "style": "solid" 

Additionally, you can assign your own CSS to a specific block, element, or the root.
   For example, the code below applies a red text color to a table block:

"border":  "color": "#ff0000", "width": "20px", "style": "solid" 

Color styles

The color property lets the user to set background, gradient, as well as the color of text.
   Keys to colors:

• background -- Sets the background color for the block or element.
• gradient -- Defines an outline gradient that is used for the block.
• text -- controls the color of the text.

The following example sets a black background with white text in every area for each page:

"color":  "background": "#000000", "text": "#ffffff" 

CSS

The CSS property lets you add custom styles to specific classes. It allows you to have more control over the theme's style.

Example: Apply custom styles to wp-block-template-parts and wp-block-button, and add a hover effect for the button:

"css": ".wp-block-template-part  background-color: #777777; padding: 20px;  .wp-block-button__link:hover  background-color: #ffffff; color: #000000; "

It is evident that the header and footer template elements are given background-color and padding, while the hover state for the button is white with black text.

Dimensions

Dimensions property allows you to control the dimension property permits you to control the width, height and proportions of blocks.

Keys for dimensions:

• aspectRatios -- Defines custom aspect ratios for elements.
• minHeight --- Sets the height that is required for blocks.

Example to create a custom aspect ratio of 3:1 for an image block:

"blocks":  "core/image":  "dimensions":  "aspectRatio": "custom"   

However, the above alone does not suffice. You have to add your "custom" style within the settings sections.

"dimensions":  "defaultAspectRatios": true, "aspectRatios": [  "name": "Custom Ratio 3:7", "slug": "custom", "ratio": "3/7"  ] 

You can see here that you can see that the "Custom Ratio" option is now available. If you prefer to remove the seven default aspect ratios, remove "defaultAspectRatios":true from the settings section.

Styles specific to the element

The element property lets you apply specific styles to HTML elements such as links and buttons or headings.

As an example, the code below turns off the text decoration (underlining) on all hyperlinks:

"elements":  "link":  "typography":  "textDecoration": "none"   

Filter

Filter property filter property allows you to apply CSS-like filter effects (e.g. blur and brightness) to specific blocks, similar to images.

Exemple: Apply a blur and a brightness filter to the image block

"blocks":  "core/image":  "filter":  "duotone": "blur(5px) brightness(0.8)"   

The blurring and brightness effects are added to the image block. The other filter choices are:

• contrast --Adjusts the contrast of the element.
• grayscale --Converts the element into grayscale.
• Invert -Inverts the colors of the element.Inverts the colors that the elements display.
• transparency -Controls the transparency of the element. Controls the transparency of the element.
• Saturate •Increases or decreases the intensity of the colors.
• sepia ---Applies an edgy tone to the element.

Outline

outline property defines styles for outlines. outline property defines styles for outlines drawn outside the element's boundary, but without impacting the layout area.

The outline of the key points:

• color --Sets the color of the outline.
• offset offsetControls the area between the border and outline.
• style CSS styleSpecifies the style of outline (e.g. dots or solid).
• wide ---Sets the dimensions of the outline.

Example Use a red dotted outline to an icon:

"elements":  "button":  "outline":  "color": "#ff0000", "style": "dotted", "width": "4px"   

Shadow style

This shadow property lets you add shadows from boxes to block elements that add depth and a sense of the luster to your elements.

Example: Apply a shadow on every image

"blocks":  "core/image":  "shadow": "0 10px 20px 0 rgb(0 0 225 / 0.50)"  

Spacing styles

The spacing property handles the padding, margin, and block gap styles that you want to use for your theme.

Space-related keys:

• blockGap --Controls the gap between blocks.
• margin -- Sets the margins of blocks.
• padding --Controls padding within blocks.

The example below creates an individual padding for the right and left sides.

"spacing":  "padding":  "left": "min(6.5rem, 8vw)", "right": "min(6.5rem, 8vw)"  

Typography styles

The typography property controls size, font styles as well as other settings related to text.

Keys for common typography keys:

• fontFamily ---Sets the font family used for the text.
• fontSize --Defines the size of the font.
• fontStyle - fontStyle Specifies the font style (e.g., italic, normal).
• fontWeight ---Controls the amount (thickness) of the font.
• LetterSpacing -The -Adjusts space between letters.
• lineHeight --Defines the line's height (spacing between the lines of text).
• textAlign TextAlign HTML0Sets the text alignment (e.g., left center, right, etc.).
• textColumns -TextColumns HTML0 -Controls the amount of text columns.
• textDecoration ---Sets the text decoration (e.g., underline).
• writingMode --Defines how to write (e.g., vertical, horizontal).
• TextTransform TextTransform HTML0Controls the text's transformation (e.g. uppercase, lowercase).

As an example, you could set all headings to include a font-weight of 300 and an italic-style:

"blocks":  "core/heading":  "typography":  "fontWeight": "300", "fontStyle": "italic"   

Property of patterns and templates

These three top-level properties are used to register custom assets in your theme.

1. Custom-designed templates

The templates property is used to register custom templates for different types of post.

• name the name of this .html as well as .php file located within the subdirectory templates.
• title title -- The title that will be given to the template in order for easier recognition.
• postTypes defines the kind of content (e.g. posts, articles, pages) that the template is utilized to render.

2. Template parts

TemplateParts property is used to define templates that can be reused. templateParts property can be used to specify reusable elements from templates (e.g., headers, footers).

• name is the name used to describe name -- The title of the .html or .php file that is located in the subdirectory of parts.
• title --The title that is given to the template part for easier identification.
• Area -- Indicates which area of the page that the template part applies to (e.g. header, footer, sidebar).

3. Patterns

The patterns property lets you create a variety of pattern names that are available from the WordPress Patterns Directory, making them available in the theme.

Here's how you can make a pattern registered:

"patterns": [ "my-custom-pattern-slug" ]

Three practical examples of working on theme.json

Below are some suggestions you can do for a theme you are developing.

1. Add a pattern

Here's how to include two patterns that are available in the WordPress Patterns Directory. Shown here are the "Fullscreen cover image gallery" pattern:

"patterns": [ "fullscreen-cover-image-gallery", "hero-banner-with-overlap-images" ]

    Notes:    

• The patterns pulled from the patterns directory will not display in the site editor's pattern section. They will be accessible only via inserter. inserter.
• In this instance it is the case that we are including top-level property pattern (compared with setting as well as styles and styles, which we have omitted in previous examples for brevity).

2. Adding a custom font

We downloaded two font files ( Roboto-Regular.ttf and Roboto-Bold.ttf) from the Google Fonts library and uploaded the fonts to the theme's assets/fonts/ subdirectory.

The following code registers both fonts, making them available site-wide:

"settings":  "typography":  "fontFamilies": [  "fontFamily": "Roboto", "name": "Roboto", "slug": "roboto", "fontFace": [  "fontFamily": "Roboto Regular", "fontWeight": "400", "fontStyle": "normal", "src": [ "file./assets/fonts/Roboto-Regular.ttf" ] ,  "fontFamily": "Roboto Bold", "fontWeight": "700", "fontStyle": "bold", "src": [ "file./assets/fonts/Roboto-Bold.ttf" ]  ]  ]  

3. Setting your color palette

If you wish to limit your users to only a particular colour palette, you could set it up this way. (Gradients as well as duotones may be set according to your specifications.)

    Example:    

"settings":  "color":  "custom": false, "defaultPalette": false, "palette": [  "slug": "primary", "color": "#1e8cbe", "name": "Primary" ,  "slug": "secondary", "color": "#21759b", "name": "Secondary" ,  "slug": "tertiary", "color": "#", "name": "Tertiary" ,  "slug": "accent", "color": "#464646", "name": "Accent"  ]  

Recognize these four hues? They're part of WordPress the color story.

Summary

Learning how to efficiently use properties like appearanceTools gives you more control and efficiencies when creating or refining WordPress themes, making this document a must-have tool for developers looking to create flexible, user-friendly themes.

Bud Kraus

Bud Kraus has been working with WordPress in the form of an in-class or online instructor, web developer and content writer since 2009. He has created instructional videos and written many blog posts for WordPress business.