Running with homes and key-value pairs in theme.json

Figuring out the development and houses of the theme.json record is key for block theme construction. This record serves as the main configuration hub for all block-based problems.

Whether or not or no longer you’re construction a theme from scratch, customizing an provide one, developing a technique variation, or running on a child theme, grasping learn the way to artwork with theme.json is essential.

Fortunately, JSON (JavaScript Object Notation) is a human-readable construction with a hierarchical building that organizes wisdom from commonplace to express houses. Throughout the context of theme.json, familiarity with Cascading Style Sheets (CSS) is further linked than an in-depth knowledge of JavaScript.

This newsletter objectives to break down the main and secondary (nested) houses in a theme.json record, focusing on the necessary factor settings and kinds houses. The ones are the core elements of the record, and we’ll provide detailed explanations and code examples for each and every.

We’re construction on the foundation laid in our previous article, Unleashing the ability of theme.json: Customizing your wordpress theme like a professional, specifically inside the section Running with theme.json document homes.

How sorts are rendered in a block theme

wordpress uses a built-in cascading process to render sorts for a internet web site. When a couple of sources define the an identical atmosphere or style, wordpress should come to a decision which one takes precedence. Below is the order of precedence that wordpress follows to decide which sorts are carried out:

1. wordpress core —The fallback theme.json record is inside the wp-includes list. This record is up to the moment with number one wordpress releases and should not be edited.
2. Theme — The primary theme.json record used by theme developers to stipulate the theme’s settings, sorts, and other houses.
3. Style diversifications — If a theme includes style diversifications, each and every has its private theme.json record stored inside the theme’s sorts subdirectory.
4. Child theme — As with antique problems, a child theme can regulate a parent theme without converting its knowledge (optional).
5. Child theme style diversifications — Similar to commonplace style diversifications, a child theme can have its private theme.json record in its sorts subdirectory (optional).
6. Particular person-created sorts — The ones are custom sorts added through wordpress editors (for pages, posts, or the internet web site as a whole) and stored inside the database.

The cascading order promises that sorts from higher-priority sources override those from lower-priority ones. For example, settings inside the theme’s theme.json record will override the core wordpress theme.json. Likewise, a child theme’s style variation will precede the parent theme’s style variation.

Particular person-created sorts (6) cling the easiest priority, overriding all differing types inside the cascade.

In this article, our point of interest is on the theme.json record located inside the root list of any wordpress block theme.

A reference for primary houses and their key-values

Let’s uncover the seven top-level devices in theme.json, which we’ve grouped into 3 sections to make the ideas easier to understand.

A few definitions previous to we dive in

When running with theme.json, you’re going to in all probability to seek out more than a few definitions for crucial elements. For clarity, appropriate right here’s how we define them in this article:

1. Sections — Groupings of top-level possible choices (moreover referred to as “top-level devices” in some articles).
2. Pieces — The primary elements inside the theme.json record, very similar to settings and sorts.
3. Properties — The elements within devices. For instance, the settings object incorporates 12 different houses.
4. Key-value pairs — Properties are made up of key-value pairs. A “key” represents a assets function and is enclosed in quotation marks. A “value” is in most cases a boolean, string, or array.

Once we indicate “by way of default,” we visit the default configurations inside the core theme.json record, located at wp-includes/theme.json.

Finally, “consumers” refers to someone the usage of the wordpress Admin who can regulate settings inside the internet web site, internet web page, or put up editors.

Syntax overview

1. Booleans don’t appear to be enclosed in quotes.
2. Strings are enclosed in double-quotes.
3. Arrays are wrapped in sq. brackets [].
4. Pieces are enclosed in curly braces {}, containing a couple of houses or nested devices.
5. Commas are used to separate a couple of key-value pairs within an object.

That is an example of usual syntax:

{
    "house": {
        "rooms": "kitchen"
    }
}

Grouping the houses

We’ve organized the houses into 3 sections for easier navigation:

1. Elementary houses
2. Settings and kinds houses
3. Templates and patterns houses

To simplify examples, we’ve now and again neglected the outer object wrappers. Instead of revealing the entire building:

{
    "settings": {
        "appearanceTools": false,
        "background": {
            "backgroundImage": true
        }
    }
}

We might in all probability shorten it to:

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

Elementary houses

To start with of a theme.json record, you’ll in most cases to seek out two key houses: $schema and fashion. The ones houses are normally located at the top of the record. The existing schema fashion is 3, introduced with wordpress 6.6.

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

Settings and kinds houses

If you are conversant in antique problems, believe the settings assets as choices and functions that may typically be set inside the purposes.php record and exposed inside the Glance > Custom designed section of the wordpress admin.

Sorts, on the other hand, are similar to the CSS houses that used to reside inside the sorts.css record, controlling the theme’s structure and design.

Settings

Except for the block and elements houses, all other settings are world. Since a lot of the ones settings are booleans, they act as toggles to permit or disable a UI serve as.

It’s crucial to note that not all keys practice in each context. For instance, it’s not imaginable to allow consumers to set a minimum top for a paragraph block.

Glance apparatus

The ones settings will also be enabled collectively or for my part by way of the usage of "appearanceTools": true.

Enabling this feature exposes somewhat numerous UI possible choices inside the wordpress editor, saving developers time. By means of default, the ones apparatus are disabled ("appearanceTools": false).

Keys within appearanceTools include:

• background
  • backgroundImage — Shall we within the shopper with the intention to upload a background image to blocks.
  • backgroundSize — Defines how the background image is scaled (duvet, come with, and so forth.).
• border
  • color — Lets in color selection for borders.
  • style — Lets the shopper make a choice the border style (cast, dashed, dotted, and so forth.).
  • width — Controls the thickness of the border.
  • radius — Shall we in consumers to set rounded corners by way of adjusting the border radius.
• color
  • link — Lets in atmosphere a color for links within the content material subject material.
  • heading — Lets consumers define colors for heading tags (
,

    , and so forth.).

  • button — Controls the color of buttons inside the theme.
  • caption — Shall we in atmosphere a practice color for captions.
• dimensions
  • aspectRatio — Lets consumers control the width-to-height ratio of blocks.
  • minHeight — Lets in atmosphere a minimum top for blocks.
• position
  • sticky — Shall we within the shopper to make a block sticky, because of this it stays fixed in place while scrolling.
• spacing
  • blockGap — Controls the spacing between blocks.
  • margin — Lets consumers alter the margins spherical a block.
  • padding — Controls the padding inside of a block, defining the space between its content material subject material and its border.
• typography
  • lineHeight — Shall we in consumers to control the street top (space between lines of text) for greater readability.

Example: If you want to have consumers with the intention to upload a background image while protective other glance apparatus disabled, use:

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

Blocks

The blocks assets allows consumers to permit settings consistent with block, which is in a position to override world settings.

Example: If appearanceTools is able to false, on the other hand you still wish to disclose border controls for a block, use:

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

Color

This assets we could consumers set color possible choices very similar to background color, text color, or gradients.

Keys within the color assets:

• background — Controls the background color of blocks or elements.
• custom — Lets in or disables the ability for purchasers to select custom colors.
• customDuotone — Shall we in consumers to make use of custom duotone filters to photographs.
• customGradient — Lets in custom gradient possible choices.
• defaultDuotone — Provides default duotone image filter possible choices.
• defaultGradient — Defines the default gradient possible choices available to consumers.
• defaultPalette — Controls the default color palette for the theme.
• duotone — Shall we in duotone filters on footage.
• gradient — Lets in gradient possible choices for backgrounds or other elements.
• link — Gadgets the color for links inside the theme.
• text — Controls text color possible choices.
• heading — Gadgets colors for headings (e.g., h1, h2, and so forth.).
• button — Controls button color possible choices.
• caption — Gadgets the caption color for media elements.

Let’s uncover some examples:

Example 1: If you want to disable the color picker for purchasers, you’ll have the ability to use the following:

"color": {
    "custom": false
}

Example 2: To set custom primary and secondary theme colors, you’ll have the ability to use this configuration:

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

Dimensions

This assets provides possible choices to control block dimensions, very similar to width, top, and facet ratio.

Keys within the dimensions assets:

• aspectRatio — Shall we in consumers to set or lock the facet ratio of a block (e.g., 16:9, 4:3).
• defaultAspectRatios — Defines default facet ratios for blocks.
• minHeight — Lets in the ability to set a minimum top for blocks.

For example, to allow consumers to set a minimum top for supported blocks, use the following:

"dimensions": {
    "minHeight": true
}

Construction

The structure assets allows consumers to set layout-related possible choices, very similar to content material subject material width and whether or not or no longer consumers can customize the structure. This allows consumers to set structure possible choices with the ones keys:

• contentSize — Gadgets the default width of blocks.
• wideSize — Defines the width of blocks when the massive alignment selection is selected.
• allowEditing — Determines whether or not or no longer consumers can edit structure possible choices.
• allowCustomContentAndWideSize — Lets in the customization of contentSize and wideSize.

Example: Configure structure settings with default and enormous block widths:

"structure": {
    "contentSize": "620px",
    "wideSize": "1000px"
}

Lightbox

The lightbox assets allows consumers to permit the “Magnify on click on on” serve as for footage, opening them in a larger view when clicked.

Keys within the lightbox assets:

• enabled — Lets in or disables the lightbox serve as.
• allowEditing — Shall we in consumers to toggle the lightbox atmosphere.

Example: To allow consumers to toggle the lightbox serve as for footage, use this configuration:

"blocks": {
    "core/image": {
        "lightbox": {
            "allowEditing": true
        }
    }
}

Position

The position assets allows consumers to control the location of blocks, very similar to making a block sticky on the internet web page.

Example: Make a block sticky:

"position": {
    "sticky": true
}

Shadow

This assets we could consumers practice shadow effects to blocks, each by way of the usage of predefined presets or custom-defined shadows.

Keys within the shadow assets:

• defaultPresets — Lets in or disables default shadow presets.
• presets — Shall we in consumers to stipulate custom shadow presets.

Proper right here’s an example where default shadows are changed into off, and a practice shadow named “Natural” is defined:

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

The numbers indicate the click-steps taken inside the internet web site editor to show the UI. The total step shows the “Natural” shadow.

Spacing

This assets defines how spacing (padding, margin, hollow) is controlled inside the editor.

Keys within the spacing assets:

• blockGap — Controls the gap between blocks.
• margin — Shall we in consumers to set margins spherical blocks.
• padding — Provides possible choices to set padding inside of blocks.
• units — Defines the available units for spacing (e.g., px, rem).
• customSpacingSize — Shall we in consumers to set custom spacing sizes.
• spacingSizes — Defines a range of preset spacing sizes.
• spacingScale — Shall we in for scaling of spacing units.

Example: To limit consumers to two units of dimension (pixels and rem) for padding, margins, widths, and heights, and to show the spacing controls inside the internet web site editor, set appearanceTools to true and configure like this:

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

Typography

This assets controls the text-related settings on your theme, very similar to font measurement, weight, and line top.

Keys within the typography assets:

• defaultFontSizes — Defines the default font sizes available to consumers.
• customFontSize — Lets in or disables the ability to set custom font sizes.
• fontStyle — Controls the way in which of the font (e.g., common, italic).
• fontWeight — Shall we in consumers to set the load of the font (e.g., bold, delicate).
• fluid — Lets in fluid typography, adjusting font measurement dynamically in line with computer screen measurement.
• letterSpacing — Controls the spacing between letters.
• lineHeight — Gadgets the height of each and every line of text.
• textAlign — Shall we in control over text alignment (e.g., left, middle, right kind).
• textDecoration — Provides possible choices for text decoration (e.g., underline).
• writingMode — Gadgets the writing mode for the text (e.g., horizontal or vertical).

Example: To disable every custom font sizes and ropCap possible choices, use the following:

"typography": {
    "customFontSize": false,
    "dropCap": false
}

In this case, both a kind of highlighted keys will not appear inside the editor.

Root padding aware alignments

When set to true, this assets promises that vast or full-width block alignments are conscious about the padding carried out to the foundation part of the internet web page (e.g., or ), ensuring right kind alignment although padding is carried out.

Example:

"useRootPaddingAwareAlignments": true

When set to true, you’ll have to moreover define the foundation’s top, right kind, bottom, and left padding values as a technique. (Further about style houses below).

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

Applying the useRootPaddingAwareAlignements atmosphere along with right kind and left padding to the body (as inside the above code) ends up in the following.

Sorts

The sorts assets means that you can practice CSS sorts to the foundation (default), explicit elements, or particular person blocks on your theme.

Background sorts

You’ll control background-related houses, very similar to footage, positioning, and attachments.

No longer abnormal keys for background:

• backgroundImage — Defines the background image for the block or part.
• backgroundPosition — Gadgets the location of the background image (e.g., middle, top-right).
• backgroundRepeat — Specifies whether or not or no longer the background image repeats (e.g., repeat, no-repeat).
• backgroundSize — Controls the scale of the background image (e.g., duvet, come with).
• backgroundAttachment — Specifies whether or not or no longer the background image is fixed or scrolls with the internet web page.

For example, you’ll have the ability to set a background image on your theme:

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

Block certain types

You’ll practice certain types, very similar to shadow, typography, and borders, to particular person blocks.

Keys for border:

• color — Defines the color of the border.
• radius — Gadgets the border-radius for rounded corners.
• style — Specifies the way in which of the border (e.g., cast, dotted).
• width — Controls the width of the border.
• top, right kind, bottom, left — Lets you set particular person border sorts for each and every side.

For example, the following devices a 20px cast pink border spherical the entire internet web page:

"border": {
   "color": "#ff0000",
   "width": "20px",
   "style": "cast"
}

You’ll moreover assign custom CSS to a specific block, part, or the foundation.
For example, the code below applies a pink text color to a table block:

"border": {
   "color": "#ff0000",
   "width": "20px",
   "style": "cast"
}

Color sorts

The color assets means that you can control background, gradient, and text color settings.
Keys for color:

• background — Gadgets the background color of the block or part.
• gradient — Defines a background gradient for the block.
• text — Controls the color of the text.

The example below devices a black background with white text on each part for each internet web page:

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

CSS

The css assets means that you can attach custom sorts to express classes, allowing further granular control over theme sorts.

Example: Observe custom sorts to wp-block-template-parts and wp-block-button, and add a hover affect for the button:

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

As you’ll have the ability to see, the header and footer template elements are assigned background-color and padding, while the hover state for the button has a white background with black text.

Dimensions

The dimensions assets means that you can control the width, top, and side ratio of blocks.

Keys for dimensions:

• aspectRatios — Defines custom facet ratios for elements.
• minHeight — Gadgets the minimum top for blocks.

Example: Create a practice facet ratio of 3:7 for an image block:

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

Alternatively, the above alone isn’t sufficient. You’ll have to test within the “custom” style within the settings sections.

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

Proper right here you’ll have the ability to see that the “Custom designed Ratio” selection has been added. If you want remove the seven default facet ratios, remove "defaultAspectRatios":true from the settings section.

Part-specific sorts

The elements assets means that you can practice sorts to express HTML elements very similar to links, buttons, or headings.

For example, the code below turns off text decoration (underlining) for all links:

"elements": {
   "link": {
       "typography": {
           "textDecoration": "none"
       }
   }
}

Filter

The filter assets means that you can practice CSS-like filter effects (e.g., blur, brightness) to positive blocks like footage.

Example: Observe a blur and brightness filter to an image block:

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

Proper right here, blurring and brightness effects were carried out to the image block. Other available filter values include:

• difference — Adjusts the consideration of the part.
• grayscale — Converts the part to grayscale.
• invert — Inverts the colors of the part.
• opacity — Controls the transparency of the part.
• saturate — Will building up or decreases the saturation of colors.
• sepia — Applies a sepia tone to the part.

Outline

The outline assets defines sorts for outlines drawn outside the part’s border, without affecting structure space.

Keys for outline:

• color — Gadgets the color of the outline.
• offset — Controls the space between the border and outline.
• style — Specifies the outline style (e.g., dotted, cast).
• width — Gadgets the width of the outline.

Example: Observe a pink dotted outline to a button:

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

Shadow sorts

The shadow assets means that you can practice box shadows to blocks, together with depth and emphasis to elements.

Example: Observe a shadow to all footage:

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

Spacing sorts

The spacing assets manages the padding, margin, and block hollow sorts on your theme.

Keys for spacing:

• blockGap — Controls the gap between blocks.
• margin — Gadgets margins spherical blocks.
• padding — Controls padding within blocks.

This example below devices custom padding on the left and right kind facets:

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

Typography sorts

The typography assets manages font sorts, sizes, and other text-related settings.

No longer abnormal keys for typography:

• fontFamily — Gadgets the font family for the text.
• fontSize — Defines the font measurement.
• fontStyle — Specifies the font style (e.g., italic, common).
• fontWeight — Controls the load (thickness) of the font.
• letterSpacing — Adjusts the spacing between letters.
• lineHeight — Defines the street top (spacing between lines of text).
• textAlign — Gadgets the text alignment (e.g., left, middle, right kind).
• textColumns — Controls the collection of text columns.
• textDecoration — Gadgets the text decoration (e.g., underline).
• writingMode — Defines the writing mode (e.g., horizontal, vertical).
• textTransform — Controls the transformation of text (e.g., uppercase, lowercase).

For example, you’ll have the ability to set all headings to have a font-weight of 300 and an italic style:

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

Templates and patterns houses

The ones 3 top-level houses are used to test in custom assets on your theme.

1. Custom designed templates

The templates assets is used to test in custom templates for somewhat numerous put up types.

• establish — The establish of the .html or .php record located inside the templates subdirectory.
• title — The title that will probably be assigned to the template for easier identification.
• postTypes — Specifies the type of content material subject material (e.g., posts, pages) that the template is used to render.

2. Template elements

The templateParts assets is used to stipulate reusable elements of templates (e.g., headers, footers).

• establish — The establish of the .html or .php record located inside the elements subdirectory.
• title — The title given to the template phase for easier identification.
• house — Specifies which part of the internet web page the template phase applies to (e.g., header, footer, sidebar).

3. Patterns

The patterns assets means that you can test in an array of pattern slugs from the wordpress Patterns Checklist, making them available inside the theme.

Proper right here’s learn the way to test in a pattern:

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

3 good examples of running with theme.json

Proper right here are a few things likelihood is that you’ll wish to do for a theme you may well be developing.

1. Add a pattern

Proper right here’s learn the way to return with two patterns from the wordpress Patterns Checklist. Confirmed right here’s the “Fullscreen Cover Image Gallery” pattern:

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

wordpress.png” alt=”Demonstrates the insertion of a pattern from wordpress.org” width=”1001″ height=”471″/>

Notes:

• Patterns pulled from the Patterns list gained’t display inside the internet web site editor’s Pattern section. The ones patterns will probably be available highest all the way through the Inserter.
• In this example, we include the top-level assets patterns (compared to settings and sorts, which we neglected in previous examples for brevity).

2. Together with a practice font

We downloaded two font knowledge (Roboto-Not unusual.ttf and Roboto-Bold.ttf) from the Google Fonts library and uploaded them to our theme’s assets/fonts/ subdirectory.

The following code registers every 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. Atmosphere your color palette

If you want to restrict your consumers to a specific color palette, you’ll have the ability to configure it like this. (Gradients and duotones will also be configured in step with 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 the ones 4 colors? They’re part of wordpress’ color story.

Summary

This newsletter highlights the pivotal serve as of theme.json in stylish wordpress theme building. By means of mastering theme.json, you’ll have the ability to utterly customize your theme’s visual design and shopper interface without having complicated PHP or CSS overrides.

Figuring out learn the way to effectively use houses like appearanceTools provides higher control and efficiency when construction or refining wordpress problems, making this record an essential software for developers taking a look to create flexible, user-friendly problems.

The put up Running with homes and key-value pairs in theme.json appeared first on Kinsta®.

wordpress Maintenance Plans | wordpress hosting

read more