Through key-value pair pairs and property names in theme.json

Mar 28, 2025

-sidebar-toc> -language-notice>

If you're creating an entirely new theme, altering one that you have already to create new style in the process of development of an existing theme getting the basic understanding of theme.json is essential.

This guide will assist you to learn about the primary and second (nested) aspects in the theme.json file, specifically focusing on the main styling and settings properties. These are the most important elements in the file and will provide a detailed explanation and codes for each.

The foundation was laid in the earlier piece and in particular the final section .

What styles are possible to render with blocks?

WordPress uses the cascading mechanism that is built into the program to display different styles and designs on web pages. If several sources utilize the same settings or styles, WordPress must determine which one is the most significant. The order of precedence that WordPress uses to determine what styles should be utilized:

  1. WordPress The Core The fallback theme.json file is within the wp_includes directory. The file is regularly updated to reflect 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 various other aspects.
  3. Style variants If a theme contains styles variants, each comes with their own theme.json file stored in subdirectories that are dedicated to themes. styles.
  4. Theme designed for kids Similar to conventional themes the children's theme has the ability to change the theme's parent without changing the theme's files (optional).
  5. Theme styles of kids like the standard themes, children's themes could contain their distinct theme.json file in the subdirectory under the theme (optional).
  6. Styles that are created by the user (these are custom designed designs that are added to the site by WordPress editors (for pages, posts or even the entire site together) and then stored within MySQL. MySQL database.

The cascading pattern makes sure that themes from top-quality sources are more popular than those from lower priority sources. As an example it is the settings of themes in' theme.json file are able to override the base WordPress theme.json. Also, a theme's personal styles will be different from the appearance of the theme's parent.

User-created designs (6) have the top priority, excluding the styles of other designers within the same cacade.

In this blog this blog post, we'll concentrate on theme.json which refers to an important theme.json file located in the root directory for all WordPress themes that are blocked.

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

We'll look at seven of the most frequently used objects in theme.json, which have been divided into three categories in order to make it simpler to comprehend.

Some definitions before entering into

If you're working with theme.json, you are likely to find different definitions for the key elements. To help make the concept clearer Let's take a look at the way we can define them in this post:

  1. Sections Sections, which are high-level possibilities (also referred to as "top-level objects" in some article).
  2. objects-- The primary components of the theme.json file, which includes the settings and style.
  3. Properties They are the elements that make up objects. For instances, objects that are set for instance set object is composed twelve properties.
  4. Key-value pair properties comprise key-value pairs. The term "key" is the attribute of the property, which is surrounded by quotation marks. The expression "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 do not required to be contained within quotation marks.
  2. Strings are enclosed within double quotes.
  3. arrays are wrapped in circular brackets. arrays are wrapped in brackets which contain.
  4. Its components are contained in curly braces{ . Every object is enclosed with curly braces. They contain a variety of characteristics, or objects that are placed within.
  5. Commas can be used to distinguish the different keys-value pairs that are contained in a particular object.

Here's a sample of a typical syntax:

 "house": "rooms": "kitchen" 

The mixture of properties

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

  1. Basic properties
  2. The properties of settings and styles
  3. Templates and patterns are property of

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

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

The term could be reduced into:

"appearanceTools" False "background": "backgroundImage" True

Basic properties

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

Property properties of Styles and Setting

If you're familiar with the classic themes, think about setting properties as a way to gain access to features and functions that are typically stored within the theme's file system which can be accessed via Appearance section. Custom Section in The WordPress administrator.

The Styles are, however, similar to CSS properties, which used to exist within the styles.css file, which control the layout and design.

Settings

Apart from the properties that the block or elements' properties, other options are applicable globally. Since the large majority of those settings use Boleans, they work as toggles that allow or block the UI choices.

It's crucial to be aware that there are different keys applicable to all situations. It is, for instance, impossible for users to determine the appropriate height in a paragraph block.

Appearance documents

The options are accessible separately or in conjunction with "appearanceTools" It is the solution is yes..

Keys within appearanceTools include:

  • background
  • backgroundImage allows the user to apply the background image to the blocks.
  • backgroundSize is the method through which background pictures are reduced in size (cover or contain. ).
  • HTML1 border border
  • color allows the color of the border to be altered.
  • 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 determine corner angles by changing the radius of the border.
  • Color
  • link permits setting the color of links within the text.
  • heading allows users to discern the color of heading tags (

,

, etc. ).

  • button controls the color of buttons used within the theme.
  • caption lets you set the colors of captions which can be changed.
  • dimensions
  • aspectRatio lets users control the ratio width to height of blocks.
  • minHeight lets you define the height that blocks must be at.
  • position Position
  • sticky lets the user create a block of sticky that remains in place during scrolling.
  •  spacing
  • blockGap -- Controls block spacing.
  • margin Users can alter the margins of the block.
  • padding manages the padding within the element. It also decides on the distance between its contents and its border.
  • typography
  • lineHeight lets users adjust the size of lines (space between text lines) to make it easier for readers.

Example: If you want users to upload a background image, you must keep the other applications to hide the appearance. Utilize:

"appearanceTools": false, "background": "backgroundImage" True
The resulting UI which allows users to add a background image to a group block
The UI lets users apply an image as a background to a group block that is already placed.
Blocks

blocks property allows users to enable specific settings for each block. blocks property permits users to set up settings for each block. It is possible to override the settings of the whole block.

Examples: If appearanceTools is set to false, but you still want to display borders on your block, you can use

"border": "color": true, "style": true, "width": true, "radius": true 
Showing the resulting UI which allows adding borders
The interface for users lets you add borders.
Color

The feature lets users pick the colors of backgrounds, color gradients, colors for text and much more.

Keys which are made up of the color property

  • background regulates the color of background colors for components or elements.
  • personal -- Enables or deactivates the option to allow users to select certain colors.
  • CustomDuotone lets people create unique Duotone filters on images.
  • customGradient -- Enables custom gradient options.
  • defaultDuotone -- Provides default duotone image filter options.
  • defaultGradient determines the default gradient options available for users.
  • defaultPalette The setting sets the default color palette for the theme.
  • duotone -- Allows duotone filters on images.
  • gradient * allows gradients to be used for backgrounds as well as other elements.
  • hyperlink determines the colors for links in the theme.
  • text -- Text color control.
  • heading * Sets colours for headings (e.g., h1, h2, etc. ).
  • button Color control for buttons.
  • caption • Decides the hue of captions to be applied to multimedia elements.

Here are some instances:

Example 1. If you would want to turn off the option that lets users select colors to users can do this:

"color": "custom" False
Disabling the color picker UI
You can enable the color picker's users interface.

Example 2. For customizing primary themes colors as well as secondary colors, it's possible to make use of this configuration:

"color": "palette": [ "slug": "primary", "color": "#0000ff", "name": "Primary" , "slug": "secondary", "color": "#ff0000", "name": "Secondary" ] 
The resulting UI setting primary and secondary theme colors
The result is which is used to determine the primary theme and secondary colours.
Dimensions

The property allows you to control the dimensions of your block, such as dimensions the width, height, and aspect proportion.

Keys in the dimensions of property

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

For instance, to permit users to set a maximal height for blocks being to be supported, use the following steps:

"dimensions": "minHeight" True
Minimum height set in the UI
The minimum height is determined by the UI.
Layout

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

  • ContentSize -The isSets the width that is the default width for blocks.
  • wideSize -The wideSize - Defines the size of the block in the event that the wide alignment option is selected.
  • permitEditing AllowEditingDetermines the extent to which users are able to alter layout options.
  • allowCustomContentAndWideSize -- Enables the customization of contentSize and wideSize.

Example Layout settings can be configured using default block and wide blocks:

"layout": "contentSize": "620px", "wideSize": "1000px" 
Resulting default and width block settings
This results in an default block width and block size settings.

The property Lightbox the lightbox property lets users allow users to enable the "Expand when clicked" feature to photographs. The images can be opened in a larger image when you click.

Keys that are part of lightbox properties. lightbox property

  • disabled * Allows or disabling the feature of lightbox.
  • permitEditing lets users alter the lightbox settings.

Example:To allow users to alter the lightbox feature to display images, you can try this option:

"blocks""allowEditing"
Toggle for lightbox effect exposed
The effect of the lightbox is switched off when the lightbox effect is visible.
Position

This property of location permits users to change the location of blocks by placing them in an adhesive surface to the left.

Example Block stick:

"position": "sticky" is true
Shadow

This property lets users create shadow effects for blocks in various ways, using template designs that have been predefined, or using custom-designed shadows.

Keys within the shadow property

  • default Presets defaultPresetsEnables or disables the default presets for shadows.
  • pre-sets --Allows users to set specific setting for shadows.

This is an example of the way the default shadows are turned off. The custom shadow called "Natural" can be described as follows:

"shadow": "defaultPresets": false, "presets": [ "name": "Natural", "slug": "natural", "shadow": "6px 6px 9px rgba(0, 0, 0, 0.2)" ] 
Setting shadow options in the UI
The options for shadows can be changed in the UI.

These numbers show the various processes that can be performed within the editor with the intention of showing the user interface. In the end it is possible to see the steps to make shadows that are "Natural" shadow.

Spacing

This property outlines the method the spacing (padding margins or gaps) is managed by editors.

Keys in the area house

  • blockGap controls the space between blocks.
  • margin * allows users to create margins on blocks.
  • padding --Provides the possibility of putting padding into blocks.
  • units --Defines the units accessible for spacing (e.g. (px as well as (rem as well).
  • CustomSpacingSize ItAllows users to define the custom size of spacing.
  • spacingSizes --Defines the range that is predefined for spacing sizes.
  • spacingScale --Allows the scaling of spacing units.

Example: To limit users to two measurements (pixels and the rem) for establishing the margins of padding, width and pixels as well as widths and heights in addition to displaying the spacing control within the editor for your website to adjust the appearanceTools under the heading called appearance tools to the correct setting and configure it according to the following:

"spacing": "units": ["px", "rem"] 
Setting shadow options in the UI
Limiting the use of two measurement units.
Typography

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

Keys which are included in 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 appearance of the font (e.g. italic, normal).
  • fontWeight -ItAllows users to choose the amount of weight to the typeface (e.g. Light and bold, light and bold or light, etc. ).
  • fluid ---Enables fluid typography. It can adjust the font's size dynamically depending on screen size.
  • letterSpacing (or )Controls how there is space between the 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 function is used to set the type of writing you wish to apply for the content that you're writing (e.g. horizontal, vertical or vertical).

Example For disabling custom font dimensions as well as ropCap options, try these options:

"typography": "customFontSize": false "dropCap": false
Removing custom font size options and DropCap
The elimination of font sizes that are custom and DropCap.

If this is the case, both of these chosen keys won't always appear in the Editor.

Alignments that recognize the padding of the base

If the property has been set in its true state it ensures that wide width, or full width block alignments are aware of the padding applied to the main element on your page (e.g. or ) and guarantees that the alignment is even when padding is applied.

Example:

"useRootPaddingAwareAlignments": true

If you choose to set it as true True, then it's important to recognize the root's left, top, right, and left paddings in the style. (More details about the style's properties below).

"spacing": "padding": "top": "0", "right": "100px", "bottom": "0", "left": "100px" 
The useRotPaddingAwareAignments default
The useRotPaddingAwareAignments default.

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

Apply left and right padding when useRootPaddingAwareAlignments is set to true
Apply left and right padding when useRootPaddingAwareAlignments is set to true.

Styles

The properties of the styles property let users add CSS styles to the design's foundation (default) specific elements and also specific blocks in the theme.

Design of background

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

Common keys to back up:

  • BackgroundImage -BackgroundImage -Defines the image used to make the background image of the block or element.
  • backgroundPosition --Sets how background pictures are positioned (e.g. the center, top-right).
  • backgroundRepeat -The backgroundRepeat option Specifies how frequently the background image is repeated (e.g. repeat, no-repeat).
  • backgroundSize -(-)Controls the dimensions of the background image (e.g. covers, or even include).
  • backgroundAttachment The valueSpecifies the manner in which background images stays fixed or is scrolled in conjunction with the page.

As an example, you could choose a background image for a design.

"background": "backgroundImage": "url": "https://joyofwp.com/wp-content/uploads/2024/09/dots.png" 
Adds a background image style to all pages
Background images are added to all pages.
Block-specific styles

You are able to apply certain style like shadows, typography, and borders to the individual blocks.

Security at the border is a key factor

  • color -(-)Defines what is the colour that the border.
  • radius -(-)Sets the border-radius for corner rounded edges.
  • style CSS styleSpecifies what style borders will have (e.g. solid, dots, etc. ).
  • dimension ---Controls the border's width.
  • Bottom left, top right Right Let's define separate boundaries for each of the sides.

The following example provides a 20px solid red border across the entire page.

"border": "color": "#ff0000", "width": "20px", "style": "solid" 
Adding a border style to all pages
The border design can be added to every type of page.

In addition, you may apply your CSS to a particular block either an element or base. This example assigns the color red for a block in a table:

"border": "color": "#ff0000", "width": "20px", "style": "solid" 
Adding a text color style to all tables
The addition of a font color style to every table.
Color styles

The color property lets users specify the background color and gradient in addition to the color of text. Keys to shades:

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

The following example sets an all-black background and white text on every page:

"color": "background": "#000000", "text": "#ffffff" 
Setting text and background color styling to all pages
The font's colors and font will be the same on each page.
CSS

CSS property lets you add custom styles to classes. CSS property lets you add distinct 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; "
Showing all buttons in the header having a hover state for text and background styles
The header lists all buttons with an option to hover for backgrounds and the styles of text.

It's evident that the footer and header elements in the template have the background color and padding and the hover state of the button has black and white text.

Dimensions

Dimensions property permits you to manage the dimension property that allows you to manage the size and height ratios for the block.

Keys to dimensions:

  • aspectRatios -- Defines custom aspect ratios for elements.
  • minHeight -- This minimum height that must be considered for blocks.

An example to create a custom aspect ratio of 3:1 to an image block

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

However, the above does not suffice. You must add the "custom" style to the settings section.

"dimensions": "defaultAspectRatios": true, "aspectRatios": [ "name": "Custom Ratio 3:7", "slug": "custom", "ratio": "3/7" ] 
Adding a custom ratio styling option for all images
The inclusion of a customized ratio to each photo.

There is an option to select the "Custom Ratio" choice available. If you prefer to remove the seven default aspect ratios, remove "defaultAspectRatios":true from the settings section.

Particular designs for the component

The attribute property permits you to use specific styling styles for HTML elements like links and buttons, as well as headings.

The example shown below shows the code below will disable the text decoration (underlining) for all hyperlinks:

"elements": "link": "typography": "textDecoration": "none" 
Disabling text decoration styling for links
Disabling text decoration styling for links.
Filter

Filter property filter property allows you to apply CSS-like filters (e.g. the blurring or brightening) to specific blocks, like images.

Exemple: Apply a blur and a bright filter to the block of images

"blocks": "core/image": "filter": "duotone": "blur(5px) brightness(0.8)" 
Adding a blurring style to all images
A blurring style is added to every photo.

Blurring effects and light are also included in the image block. The other filter choices include:

  • contrast --Adjusts the contrast of the element.
  • grayscale --Converts the element to grayscale.
  • invert the colors that elements display.Inverts the colors that elements show.
  • transparency controls its transparency. It regulates the transparency of the element.
  • Saturate *Increases or lessens the intensity of the color.
  • Sepia - Sepia - Applies an unpretentious tone to the component.
Outline

outline property specifies styles for outline properties. It defines styles for. outline property defines styles for lines drawn on the exterior of an element, but and without altering the arrangement.

The main elements:

  • color ColorSets the color of an outline.
  • offset offsetControls the space between outline and border.
  • style CSS styleSpecifies the kind of outline (e.g. dots or solid).
  • large broadSets how wide the edges of the HTML0 are.

Example Make use of a red dot trace of an icon:

"elements": "button": "outline": "color": "#ff0000", "style": "dotted", "width": "4px" 
Adding an outline style to all buttons
by adding a design outline for all buttons.
Shadow style

The property of shadows property lets you create shadows on boxes and objects that create the illusion of depth as well as shimmer to your products.

Example Shadows are used for every photo

"blocks": "core/image": "shadow": "0 10px 20px 0 rgb(0 0 225 / 0.50)" 
Adds a shadow to all images
Makes shadows over all images.
Spacing styles

The spacing property handles the padding, margin and block gap types you'll need to pick to design your layout.

Space-related keys:

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

This creates a unique padding on the left and right sides.

"spacing": "padding": "left": "min(6.5rem, 8vw)", "right": "min(6.5rem, 8vw)" 
Adds left and right padding
The padding is left and right.
Styles of Typography

The property of typography property manages dimensions, font styles and additional options that relate to the text.

Keys to the most popular key types of typography:

  • fontFamily --Sets the family of fonts that is 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 WeightControls the amount (thickness) of the font.
  • LetterSpacing The letter spacingAdjusts the spacing between letters.
  • lineHeight lineHeightDefines the length of the line (spacing between text).
  • TextAlign TextAlign HTML0Sets the alignment of text (e.g. Left center, right. ).
  • TextColumns textColumns HTML0Controls the number of text column.
  • TextDecoration TextDecoration HTML0Sets the decoration of text (e.g. underline).
  • WritingMode WritingModeDefines how to write (e.g. either horizontal or vertical).
  • TextTransform TextTransform HTML0Controls the transform of the text (e.g. uppercase, lowercase).

In this way, for instance, it's feasible to modify every heading to be accompanied by a font-weight of 300 and an italic style

"blocks": "core/heading": "typography": "fontWeight": "300", "fontStyle": "italic" 
All headings include italic and weight styling properties
Each heading is highlighted and the style features of the weight.

Templates' property rights are protected by templates and patterns

The top three properties can be used to register the custom-built assets within the theme.

1. Templates that are designed specifically for design

Template properties are used to define custom templates. template property could be used to signify customized templates that can be used to represent a variety of content.

  • Name the file's name .html and .php file located within the subdirectory for templates.
  • title title The title that is to be added to the template for ease of recognition.
  • postTypes defines the kind of material (e.g. pages or articles, posts) that the template is utilized to show.

2. Parts for templates

The TemplateParts property can be used to specify templates that can be reused. TemplateParts property is a way to indicate elements that are reused within templates (e.g. headers, headers, footers).

  • name is the name that is used for describing a name. The title of name is the title of .html or .php file. It is located under the subdirectory for components.
  • title --The title is associated with the template in order for easier identification.
  • Area -Indicates the section of the web page the template component applies to (e.g. header, footer, sidebar).

3. Patterns

The pattern property lets you make patterns using a variety of names. These patterns are accessible through the WordPress Patterns Directory, making patterns available within the theme.

Here's how you can get a pattern registered:

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

Three concrete examples of how to work on theme.json

Here are a few ideas that you could use for a theme you are designing.

1. Design a pattern

This is how you can add two patterns to 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" ]
Demonstrates the insertion of a pattern from wordpress.org
Explains how you can insert an image using the assistance of wordpress.org.

Notes:

  • The patterns that are found in the patterns directory will not be visible in the site editor's pattern section. The patterns will only be available by inserter. inserter.
  • In this instance, it's the case where top-level properties are added to the layout (compared with the setting and design and the styles have been omitted previously to make it easier).

2. Adding a custom font

Two font files have been taken ( Roboto-Regular.ttf and Roboto-Bold.ttf) from the Google Fonts library and added the fonts in the theme's assets/fonts and 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" ] ] ] 
Shows the inclusion of a Google Font
The screenshot shows Google Font. Google Font.

3. Setting your color palette

If you wish to restrict your users to a specific color palette, you can configure it this way. (Gradients and duotones may be set in accordance with the requirements of your business.)

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" ] 
Demonstrated custom theme colors
Custom theme colors.

Are you familiar with these colors? They're part of WordPress the story of color.

Summary

Utilizing effectively features like appearanceTools allows you to have more control and efficiencies while developing or upgrading WordPress themes, making this document a must-have tool for designers who wish to design easy-to-use themes that are easy to use and adaptable.

Bud Kraus

Bud Kraus has been working with WordPress to teach in class or online, web developer and content writer since the year 2009. Bud Kraus has made videos to help with instruction and created numerous blog posts to help promote the WordPress business.

Article was first seen on this site

Article was first seen on here