-sidebar-toc> -language-notice>

If you're creating an entirely new theme, altering one that you have already in order to implement a fresh style, or working on the creation of an existing theme, getting the basic understanding of using theme.json is essential.

This article will help you understand both the main and second (nested) features of the theme.json file, specifically focusing on the main styling and settings properties. They are the primary elements in the file and we'll provide detailed explanations and code examples for each.

The basis was laid in the previous piece, and in particular the final section .

What kinds of styles are possible to render with a block motif?

WordPress utilizes the cascading mechanism built into the software to show different styles and designs on web pages. When multiple sources use the same settings or styles, WordPress must determine which one is the most significant. The precedence order that WordPress utilizes to select which styles are to be utilized:

1. WordPress Core The fallback theme.json file is within the wp_includes directory. This file is updated with the latest WordPress versions and shouldn't be altered.
2. Theme -- The primary theme.json file used by theme designers to determine the themes' settings, its style, and other properties.
3. Style variants When a theme includes styles variations, each one has their individual theme.json file stored in the subdirectories for themes. styles.
4. Theme for children Like conventional themes, a children's theme is able to modify the theme's parent without changing the theme's files (optional).
5. Theme styles of children similar to the regular themes, children's themes could include its own theme.json file in the subdirectory of the style (optional).
6. Styles that are created by the user (these are custom designs added by WordPress editors (for posts, pages or the site all in one) and stored inside MySQL. MySQL database.

The cascading pattern ensures that designs from high-priority sources prevail over lower-priority sources. As an example it is the theme's settings in themes' theme.json file will override the core WordPress theme.json. Likewise an individual theme's style variations will predate the style of the theme's parent.

User-created styles (6) hold the highest precedence, precluding the other styles as in the same cascade.

In this blog post, we'll be focusing on theme.json which is the theme.json file located in the root directory of any WordPress themes that block.

The discussion of the principal property as well as the value-added

Let's look at the seven most popular objects within theme.json, which we've grouped into three sections in order to make it more comprehensible.

Some definitions before entering into

If you are working using theme.json, you are likely to find different definitions for the key elements. In order to make the concept clearer, let's look at how we define them in this article:

1. Sections Sections which represent top-level choices (also known as "top-level objects" in some article).
2. Objects-- The primary elements of the theme.json file, which includes the setting and styles.
3. Properties These are the components in objects. In this case, for instance setting objects, for instance set object is composed twelve properties.
4. Key-value pair properties comprise key-value pairs. A "key" is the property's attribute, and is enclosed with quotation marks. The term "value" may be a string, boolean 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 are not have to be enclosed within quotation marks.
2. Strings are enclosed in double quotes.
3. arrays are enclosed in circular brackets arrays are wrapped in brackets that contain [.
4. Its objects are contained in curly braces{ . Each object is enclosed by curly braces. They contain a variety of properties, or objects that are nestled.
5. Commas can be used to distinguish the different keys-value pairs contained within an object.

Here's an example common syntax:

 "house": "rooms": "kitchen" 

The combination of properties

We've divided the property into three parts to make it easier navigation.

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

To simplify things, we've often removed the wrappers of outer objects. Instead of examining the whole arrangement:

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

The term could be reduced in the form of:

"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 the classic themes, think about the settings property as an option to access features and functions that are typically stored within the theme's file system which are then visible in the Appearance > Custom Section within the WordPress administrator.

The Styles however have a similarity to CSS properties that used to exist within the styles.css file, controlling the theme's layout and style.

Settings

Other than the characteristics of the blocks or element properties, the other setting are applied globally. As a majority of these settings use boleans, they function as toggles which allow or block the UI options.

It is important to remember that different keys are applicable to every situation. It's, for example, impossible for users to determine the height that is required for the paragraph block.

Appearance instruments

The settings are available either individually or together through "appearanceTools" The answer is yes..

Keys within appearanceTools are:

•       background      
• backgroundImage allows the user to add the background image to the blocks.
• backgroundSize is the method by which background images are diminished in dimensions (cover or include. ).
•       border      
• color -- Enables the border color to be changed.
• style allows users to select the type of border (solid or dashed or dashed. ).
• width regulates the thickness of the border.
• radius allows users to define corner angles by altering the radius of the border.
•       Color      
• link allows setting the color of links in the text.
• heading -- Allows users to determine the colors of heading tags (

,

, etc. ).

• button -- Controls the color of buttons used in the theme.
• caption lets you set the color of captions to be modified.
•       dimensions      
• aspectRatio allows users to manage the ratio width to height of the blocks.
• minHeight lets you set the minimum height of blocks.
•       position      
• sticky allows the user to build a sticky block that is in place while scrolling.
•       spacing      
• blockGap -- Controls block spacing.
• margin Allows users to alter the margins on the block.
• padding -- Manages the padding within the element. It also determines the space between its contents and its border.
•       typography      
• lineHeight allows users to adjust the height of lines (space between text lines) to improve reading.

Examples: If you want users to upload a background image, but keep the other applications for appearance off. Utilize:

"appearanceTools": false, "background": "backgroundImage" True

Blocks

blocks property lets users enable particular settings for every block. block property allows users to configure settings for every block. This could override settings for the entire block.

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

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

Color

The property allows users to choose the color of backgrounds, color gradients, text colors and more.

Keys which are made up of color property

• background Controls the color of background colors for components or elements.
• personalized -- Activates or deactivates the option to let users select specific colors.
• CustomDuotone lets people create unique Duotone filters on images.
• customGradient -- Enables custom gradient options.
• defaultDuotone -- Provides default duotone image filter options.
• defaultGradient defines the default gradient options available to users.
• defaultPalette The setting sets the default color palette for the theme.
• duotone -- Allows duotone filters on images.
• gradient • Allows 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 Color control for buttons options.
• caption -- Decides the color of captions to be used for multimedia elements.

Here are some instances:

Example 1. If you would like to disable the feature that allows users to choose colors to users, you could choose to do this:

"color": "custom" False

Example 2. For customizing primary theme colors and secondary colors, it is possible to utilize this configuration:

"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 in the dimension of the property

• aspectRatio lets users determine or restrict an aspect ratio for a block (e.g. 16:9, 4:3).
• defaultAspectRatios -- Defines default aspect ratios for blocks.
• minHeight permits the possibility of defining a minimum height for blocks.

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

"dimensions": "minHeight": true

Layout

Layout property Layout property lets users define layout-related settings including the width of content as well as the ability to alter the layout. Layout options can be set with these keys:

• ContentSize -The -Sets the width that is used by default for blocks.
• wideSize -The wideSize - Defines the width of the block when the wide alignment option is used.
• 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

Lightbox property lightbox property allows users to allow the "Expand when clicked" feature for images. This allows them to be opened in a larger view when they are clicked.

Keys in the lightbox property

• disabled • Enables or disabling the feature of lightbox.
• permitEditing lets users alter the settings for lightboxes.

Example:To allow users to alter the lightbox feature for images, try this setting:

"blocks""allowEditing"

Position

The property of position allows users to alter the positioning of blocks, by placing them on a sticky place to the left of the page.

Example Block stick:

"position": "sticky" is true

Shadow

This property lets users create shadow effects on blocks in a variety of ways, whether using template templates that are predefined or by making custom-designed shadows.

Keys inside the shadow property

• default Presets defaultPresetsEnables or disables the default presets for shadows.
• pre-sets --Allows users to specify particular shadow settings.

This is an example of how the default shadows are turned off, and a custom shadow called "Natural" can be described as:

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

These numbers show the various steps performed in the website editor for the purpose of showing the user interface. In the final section, you can see how to create the "Natural" shadow.

Spacing

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

Keys in the area house

• blockGap manages the spaces between blocks.
• margin * Allows users to make margins for blocks.
• padding --Provides the possibility of setting padding in blocks.
• units --Defines the units that are accessible for spacing (e.g. (px and (rem and).
• CustomSpacingSize ItAllows users to set custom spacing sizes.
• spacingSizes ---Defines the predefined range of spacing sizes.
• spacingScale --Allows the scaling of spacing units.

example: To limit users to two measurement (pixels and the rem) to establish the margins, padding and width as well as widths and heights as well as to display the spacing control in the editor on your site to adjust the appearanceTools in the section called appearance tools to the correct setting and set it up as follows:

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

Typography

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

Keys that are part of the typography property:

• defaultFontSizes defaultFontSizesDefines the default font sizes for the user to use.
• CustomFontSize CustomFontSizeEnables or blocks the capability to create custom font sizes.
• fontStyle -ItControls the look of the font (e.g. italic, normal).
• fontWeight -ItAllows users to set an amount of weight for the font (e.g. Light and bold or light, etc. ).
• fluid ---Enables fluid typography. It can adjust the size of fonts dynamically depending on screen size.
• letterSpacing (or )Controls how there is space between the letters.
• lineHeight --Sets the height of every 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 is used to set the writing mode you want to use for the text you are writing (e.g. vertical, horizontal or vertical).

Example For disabling custom font sizes as well as ropCap options, follow these options:

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

If this is the case, both of these chosen keys will ever be visible in the Editor.

Alignments that recognize the base padding

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

Example:

"useRootPaddingAwareAlignments": true

If you set it as true If true it is also necessary to identify the root's top, left, right and left paddings as the style. (More information 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 allow users to apply CSS styles to your design's foundation (default) certain elements as well as individual blocks within the theme.

Style of background

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

Common keys to back up:

• BackgroundImage -BackgroundImage -Defines the image used to create the background image for an element or block.
• backgroundPosition --Sets the direction of background images (e.g. the center, top-right).
• backgroundRepeat -The backgroundRepeat option Specifies how often the background image can be repeatedly repeated (e.g. repeat, no-repeat).
• backgroundSize -(-)Controls the dimensions of the background image (e.g., cover or include).
• backgroundAttachment -The valueSpecifies the manner in which background images stays fixed or scrolls in tandem with the web page.

For example, you can pick a background photo to create a theme.

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

Block specific styles

It's possible to apply particular styles such as shadows, typography, and borders to the individual blocks.

Keys to border security:

• color -(-)Defines the colour of the border.
• radius -(-)Sets the border-radius for corner rounded edges.
• style CSS styleSpecifies the style that the border will feature (e.g. solid, dots, etc. ).
• size --Controls the border's width.
• Bottom, top, right Left, right Let us define distinct borders for each of the sides.

For example, the following sets a 20px solid red border throughout the whole page.

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

In addition, you may apply your CSS to a particular block either an element or base. The example below assigns the red color of text to a table block:

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

Color styles

The color property permits users define background color, gradient in addition to the hue of the text.
    Keys to hues:

• background • Sets the background color of the element or block.
• gradient is an outline gradient employed to create the block.
• text can control the color of text.

The following example sets an all-black background and white text for each page:

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

CSS

The CSS property lets you add individual styles to classes. This allows you to take greater control over the theme's design.

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's evident that the footer and header elements of the template are given the background color and padding, while the hover state for the button is black and white text.

Dimensions

Dimensions property permits you to regulate the dimension property that allows you to control the width as well as the height ratios of the blocks.

Keys for dimensions:

• aspectRatios -- Defines custom aspect ratios for elements.
• minHeight -- The height is required to be used for block.

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

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

The above, however, does not suffice. You must add the "custom" style within the settings section.

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

Here, there is a "Custom Ratio" option is available. If you prefer to remove the seven default aspect ratios, remove "defaultAspectRatios":true from the settings section.

Particular styles for the component

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

In the example below, the code below will disable the text decoration (underlining) on all hyperlinks:

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

Filter

Filter property filter property permits you to apply CSS-like filters (e.g. blur or brightness) to specific blocks, similar to images.

Exemple: Apply a blur as well as a brightness filter on the block of images

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

The effects of blurring and brightness are included in the image block. The other filter choices are:

• contrast --Adjusts the contrast of the element.
• grayscale --Converts the element to grayscale.
• invert The colors are inverted that the elements display.Inverts the colors that the elements display.
• transparency controls its transparency. It controls the transparency of the element.
• Saturate *Increases or reduces the color intensity.
• Sepia --Applies an edgy tone on the component.

Outline

outline property defines styles for outlines. outline property specifies styles for lines that are drawn on the outside of an area of the element, without affecting the layout.

The main elements:

• color -Color -Sets an outline color.
• offset offsetControls the space between border and outline.
• style CSS styleSpecifies the type of outline (e.g. dots or solid).
• broad ---Sets how wide the edges are.

Example Use a red dotted outline of an icon to:

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

Shadow style

The feature of the shadow property allows you to add shadows of boxes onto elements that add the illusion of depth and the sparkle to your items.

Example Shadows are applied for 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 you'll need to choose for your design.

Space-related keys:

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

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

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

Typography styles

The typography property controls dimensions, font styles and other options related to the text.

Keys for the most common key types of typography:

• fontFamily --Sets the font family used for the text.
• fontSize -IsDefines the dimensions of the font.
• fontStyle FontStyle defines the style of font (e.g. Italic, bold or normal).
• fontWeight ---Controls the weight (thickness) of the font.
• LetterSpacing The letter spacingAdjusts the space between the letters.
• lineHeight lineHeightDefines the height of a line (spacing between texts).
• TextAlign TextAlign HTML0Sets the alignment of text (e.g. Left center, right. ).
• TextColumns textColumns HTML0Controls the quantity of text columns.
• TextDecoration TextDecoration HTML0Sets the text decoration (e.g. underline).
• WritingMode ---Defines how to write (e.g., either horizontal or vertical).
• TextTransform TextTransform HTML0Controls the text's transformation (e.g. uppercase, lowercase).

As an example it is possible to set all headings to include a font-weight of 300 and an italic-style style

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

The property rights of templates and patterns

These three top-level properties are used to register the custom-built assets within the theme.

1. Design-specific templates

The template property can be used to signify custom templates diverse types of content.

• Name the file's name .html as well as .php file located within the templates subdirectory.
• title title -- The title to be given to the template to facilitate recognition.
• postTypes determines the type of material (e.g. pages, articles, posts) that the template is used to display.

2. Template parts

TemplateParts property is used to specify templates that could be reused. TemplateParts property is a way to specify reusable elements in templates (e.g. headers, headers, footers).

• name is the name used for describing a name. The title of name is the title of .html or .php file is in the subdirectory of components.
• title --The title is assigned to the template to facilitate identification.
• Area -Indicates the section of the webpage the template component applies to (e.g. header, footer, sidebar).

3. Patterns

The patterns property allows you to create patterns with a range of names that are available from the WordPress Patterns Directory, making them available in the theme.

Here's how to make a pattern registered:

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

Three practical examples of working with theme.json

Here are some ideas you could use for a theme you are designing.

1. Create a pattern

This is how you can include two patterns on the WordPress Patterns Directory. The patterns shown here are the "Fullscreen cover image gallery" pattern:

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

Notes:

• The patterns found in the patterns directory will not be visible in the site editor's pattern section. They will be accessible only through inserter. inserter.
• In this case, it's an instance of adding top-level properties to the design (compared with setting and style and styles that we've omitted in previous examples for brevity).

2. Adding a custom font

Two font files were downloaded ( Roboto-Regular.ttf and Roboto-Bold.ttf) from the Google Fonts library and added the fonts to the theme's assets/fontsand fonts subdirectory.

The code below is able to register 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 would like to restrict your users to only a particular colour palette You could set it up this way. (Gradients and duotones may be set in accordance with your requirements.)

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" ] 

Do you recognize these hues? They're part of WordPress the color story.

Summary

Learning how to efficiently utilize properties such as appearanceTools gives you more control and efficiencies when developing or improving WordPress themes, making this document a must-have tool for designers who wish to design easy-to-use themes that are user-friendly and flexible.

Bud Kraus

Bud Kraus has been working with WordPress as an instructor in class or online, web developer and content writer since 2009. Bud Kraus has made videos for instructional purposes and has written numerous blog posts to promote the WordPress business.

Article was first seen on here