theme.json: The Design and Configuration Core of a WordPress Theme

theme.json is the schema-based configuration file that defines how a WordPress theme structures its global settings, style rules, and block-level properties. It functions as the central interface between the theme’s internal configuration and the block editor, supplying a machine-readable set of parameters that the system uses to determine which design options are available and how they inherit across the site.

Through its hierarchical structure, theme.json specifies global styles, layout constraints, spacing scales, typography settings, color definitions, and block-support features. These declarations allow the editor and front-end renderer to apply consistent styling logic, ensuring that each block and each template receives predictable defaults or aligned overrides.

Because it standardizes configuration and styling behavior, theme.json acts as the primary source of truth for full-site editing. Templates, patterns, style variations, and other theme components pull their initial values from this file, enabling WordPress to process theme configuration through a unified and interoperable model.

What is theme.json in WordPress?

theme.json is the configuration layer for block themes, enabling WordPress to load, apply, and render the theme’s design system through a consistent, schema-driven framework. It provides a machine-readable JSON structure that contains the theme’s layout models, color palettes, typography definitions, spacing scales, and support flags for individual blocks, forming the core configuration surface that WordPress reads when applying design-related settings.

Through its declarative structure, theme.json supplies the parameters WordPress uses to modify or extend default styling behavior, allowing the theme to override core presets and define its own global style rules. Its hierarchical inheritance model ensures that global settings, block configurations, and element-specific definitions propagate predictably across the editor and the front-end output.

Where Is theme.json Located and When Does It Load?

theme.json is located in the root directory of a WordPress theme and is loaded at the beginning of the theme initialization process, before any templates or stylesheets are evaluated. At this stage, WordPress reads the file to register global style values, block-support settings, and other configuration data that must be available before the editor or front-end renderer begins processing. 

Because this occurs prior to interface operations inside the WordPress admin dashboard, the file’s definitions are applied early enough to establish the theme’s defaults for both global and block-level configuration. Its position and timing ensure that WordPress can treat theme.json as the primary source of configuration overrides before additional assets or template logic run. 

File Path for theme.json

theme.json must be placed in the root directory of the active WordPress theme for WordPress to detect and load it during theme initialization. WordPress scans the theme’s top-level directory for the required files (style.css, functions.php, and theme.json) and only applies JSON-based configuration if theme.json is located at this exact level. If the file is nested inside subdirectories, WordPress will ignore it and the theme will be treated as lacking a JSON configuration layer.

Execution Timing in the WordPress Lifecycle

theme.json is processed at the beginning of the theme initialization phase, before functions.php runs and before any template files or rendering logic are evaluated. During this stage, WordPress reads theme.json and constructs the global styles configuration object, which defines default style properties, block-support settings, and editor-related parameters.

Because theme.json is evaluated before template parsing and asset generation, its definitions are available for both the block editor and the front-end renderer. This early execution ensures that all subsequent theme operations inherit the schema-defined values established when the theme is first parsed.

What Is the Top-Level Structure of theme.json?

theme.json is structured as a hierarchical JSON object whose top-level keys represent the main configuration domains of a WordPress block theme. Each key defines a specific schema section (such as global styles, settings, or block-level configuration) from which nested properties extend. This structure provides a clear organization model for the file, allowing WordPress to parse configuration data in a predictable hierarchy. The top-level keys form the basis of the schema and determine how deeper configuration layers are arranged. The following sections explain how this hierarchy is defined in the official JSON schema and outline which components are mandatory or optional within the overall configuration model.

JSON Schema and Format

The JSON Schema defines the structure that theme.json must follow and specifies which keys, data types, and nesting patterns are valid. It provides the formal syntax that WordPress uses to evaluate the file before applying any configuration. During theme loading, WordPress checks theme.json against this schema to ignore invalid entries or unsupported keys without disrupting the rest of the configuration object.

The optional $schema property points to the official schema URL, enabling tools and validators to interpret the expected format and data types correctly. Compliance with this schema ensures that WordPress can safely parse the file and retrieve the configuration values that define the theme’s stylistic and block-level settings.

Example:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "color": {
      "custom": false
    }
  }
}

Required and Optional Properties

The version property is the only required top-level key in theme.json. Its presence indicates which schema version WordPress should use when parsing the file. If version is missing, WordPress treats the file as invalid and skips JSON-based configuration entirely.

All other top-level properties (including settings, styles, templates, templateParts, and patterns) are optional. These keys activate specific configuration domains such as global styles, block support settings, layout definitions, and reusable design components. While a file containing only version is technically valid, additional keys are required to supply meaningful configuration values. These optional properties define the theme’s styling parameters, editor defaults, and block-level behavior within the full-site editing system.

What Are the Supported Versions of theme.json?

theme.json uses a versioned schema model in which the version property specifies the schema rules WordPress should apply when reading the file. Each version corresponds to a defined set of supported keys, data types, and nesting structures aligned with specific WordPress release ranges. When WordPress loads a theme, it checks the version value to determine which configuration features are available and how the file should be validated.

This versioning system allows the schema to evolve while preserving backward compatibility. Older themes can continue to function under earlier versions, while newer themes can use additional configuration domains introduced in later schema updates. 

Version 1 (WP 5.8)

Version 1 of theme.json was introduced in WordPress 5.8 and included the first schema for JSON-based theme configuration. It supported a limited set of global settings such as color palettes, typography presets, and basic layout values. 

The schema recognized only a small number of top-level keys, allowed shallow nesting, and lacked support for block-level configuration, responsive structures, and advanced inheritance rules. Because of these constraints, Version 1 provided only a minimal configuration layer and did not integrate with the full-site editing system. It remains available for backward compatibility but is not suitable for modern block theme development.

Version 2 (WP 5.9–6.5)

Version 2 was introduced in WordPress 5.9 and served as the primary schema through WordPress 6.5. It defined the stable format used by full-site editing themes by supporting both global and block-specific configuration domains. This version established the separation between settings and styles, added deeper nested structures, and formalized the inheritance rules that determine how global values propagate to blocks. 

Version 2 enabled themes to declare styling defaults, block support flags, and layout parameters in a consistent and predictable schema. Due to its stability and backward compatibility, Version 2 remains widely used across active WordPress installations.

Version 3 (WP 6.6+)

Version 3, introduced in WordPress 6.6, updated the schema with more detailed selector configuration, higher specificity control, and performance improvements in style generation. It retained the Version 2 architecture while adding support for semantic selectors, refining targeting rules, and reducing CSS output by generating only the styles needed for active contexts. 

The improvements in Version 3 allow WordPress to compile styles more efficiently and apply selector logic with greater precision. It is fully backward-compatible and represents the most optimized, selector-aware schema currently available.

What Does the $schema Property Do?

$schema defines the URL of the JSON Schema that describes the structural expectations of theme.json, serving as a reference that links the file to its formal specification. As an optional metadata property, it does not alter theme behavior or influence how WordPress interprets configuration during runtime. 

Instead, $schema connects the document to schema-aware tools, enabling structural validation, autocomplete, and specification mapping within compatible editors. This reference assists external tooling in interpreting the file’s JSON structure, key hierarchy, and allowable values through schema hinting and validation rules. WordPress ignores the property during execution, meaning theme.json remains fully functional with or without $schema, which serves only to enhance development-time clarity and tooling compatibility.

How to Configure Editor Tools Using settings?

The settings section in theme.json defines which editor tools and customization features are available in the WordPress block editor. These settings determine the visibility and behavior of UI controls for color management, typography options, spacing tools, layout parameters, and other design-system primitives. Because these options control the editor interface rather than the final visual output, they are used to standardize editing workflows, simplify the UI, or enforce design-system constraints that align with broader backend development requirements.

Settings can be declared at the global level or overridden for individual blocks, allowing themes to apply different capability rules across structural and content-specific components. 

Main Categories Inside settings

The settings object in theme.json is divided into several top-level categories that control which editing tools are available in the block editor. Each category manages a specific configuration domain:

• color: defines access to color palettes, gradients, and the ability to use custom values or theme-defined palettes.
• typography: configures controls for font families, font sizes, line height, letter spacing, and other typographic parameters.
• spacing: manages margin, padding, block gaps, and other spacing properties used to establish consistent spatial structure.
• layout: specifies layout rules such as content width, wide alignment settings, and layout container behavior.
• border: governs controls for border width, radius, style, and related frame properties.
• blocks: provides block-specific overrides for any of the above categories, allowing themes to adjust tool availability on a per-block basis.

How to Apply Global and Block-Level Styles Using styles?

Styles in theme.json define the visual rendering rules that apply to both global design defaults and block-level overrides, forming the declarative layer that governs how a WordPress site is visually output across the editor and frontend. 

Operating as a hierarchical configuration object, the styles object establishes top-level presentation logic for categories such as color, typography, spacing, layout, and borders, while enabling nested block-specific rules that selectively override global declarations. This structure maps directly into the compiled CSS that WordPress generates for both editor rendering and front end development, ensuring that visual categories are expressed consistently across environments. 

Unlike settings, which control tool availability within the editor, styles controls the actual appearance of elements and blocks, functioning as the theme’s visual configuration engine.

{
  "styles": {
    "color": {},
    "typography": {},
    "blocks": {
      "core/paragraph": {
        "color": {},
        "spacing": {}
      }
    }
  }
}

Main Categories Inside styles

The styles object defines the visual properties that WordPress applies to both the editor interface and the front-end output. Each top-level category controls a specific design domain:

• color: sets rules for text color, background color, gradients, and related chromatic properties.
• typography: manages font families, font sizes, line height, letter spacing, and other text-presentation parameters.
• spacing: configures margin, padding, and block-gap values that determine spatial structure.
• dimensions: applies width, height, and min/max constraints that control component sizing.
• border: defines border radius, width, style, and color for edge treatment.
• layout: specifies alignment rules, content width, and container-flow behavior.
• elements: assigns global styles to specific HTML elements such as links, headings, and buttons.
• blocks: provides block-level overrides for any of the above categories, enabling targeted refinements within individual block types.

What Is the Difference Between settings and styles?

settings and styles in theme.json serve different roles within the WordPress configuration model.

• settings defines which editor tools are available to users by enabling or limiting controls for color, typography, spacing, layout, borders, and block-specific capabilities. These configurations shape the block editor interface and establish the functional boundaries of the design system.
• styles, in contrast, determines the visual output of the theme. It applies the actual color values, typography rules, spacing properties, layout definitions, border characteristics, and other presentation parameters that appear in both the editor preview and the frontend.

While both sections share similar design categories, the settings object regulates tool availability and interface behavior, and styles defines the CSS rules WordPress generates. Together they maintain a clear separation between configuration control and visual rendering, ensuring consistent behavior across global, element-level, and block-level contexts.

How to Register Custom Templates in theme.json?

Custom templates are registered in theme.json using the customTemplates array, which provides the metadata WordPress needs to recognize and expose templates in the block editor. Each entry defines the template’s name (slug), title, and the postTypes it applies to. This registration step makes the template selectable for the specified content types but does not define any block structure or markup. Instead, it integrates the template into the WordPress template hierarchy by supplying the identifying data required during template resolution. Template parts are handled separately and operate as reusable layout components rather than full template registrations.

Example:

{
  "customTemplates": [
    {
      "name": "custom-home",
      "title": "Custom Home",
      "postTypes": ["page"]
    }
  ]
}

How to Register Template Parts in theme.json?

Template parts are registered in theme.json via the templateParts array, which provides the metadata WordPress uses to identify and categorize reusable layout sections, such as headers, footers, and other structural regions. Each entry specifies a name (used as the slug), a title (the label shown in the editor), and an area that assigns the part to a semantic region of the layout. 

This registration step makes the part available in the Site Editor. It allows full templates to reference it as a modular component, while the actual block markup is stored in separate .html files within the theme’s template-parts directory. By defining the part’s metadata and semantic placement, theme.json ensures WordPress can correctly incorporate it into the block template system.

Example:

{
  "templateParts": [
    {
      "name": "header",
      "title": "Site Header",
      "area": "header"
    },
    {
      "name": "footer",
      "title": "Site Footer",
      "area": "footer"
    }
  ]
}

How to Use the patterns Key to Register Block Patterns?

Block patterns are registered in theme.json using the patterns array, which provides the metadata WordPress needs to list them in the editor’s pattern library. Each pattern entry defines a name (slug), a title, and optional descriptive fields that help identify the pattern in the editor interface. The actual block markup is stored separately in .html or .php files within the theme’s patterns directory, and WordPress links the metadata in theme.json to the corresponding file based on the pattern’s slug.

This registration method treats patterns as reusable content presets rather than full templates or template parts. It allows themes to offer predefined sections (such as hero layouts, callout blocks, or grouped content structures) while keeping the design-system configuration separate from the pattern markup. Once registered, the patterns appear in the block inserter and can be added to content like any other editor component.

Example:

{
  "patterns": [
    {
      "name": "hero-banner",
      "title": "Hero Banner",
      "description": "A wide hero section with a heading and CTA."
    }
  ]
}

How Does the Cascade of theme.json Overrides Work?

The cascade of theme.json overrides follows a fixed priority sequence that WordPress uses to resolve both settings and styles. WordPress begins with its core defaults, then applies the active theme’s theme.json values, including any block-specific entries defined within the file. After theme configuration is loaded, WordPress applies user-defined changes made through the Global Styles interface, and finally applies block-level customizations added directly in the editor.

In this model, theme-level definitions provide the global baseline, block-level entries refine those values for individual components, and user customizations take precedence across all scopes. The same order applies to settings and styles, ensuring consistent resolution while still allowing granular adjustments. 

Full Hierarchy of Style Sources

WordPress resolves styles using a fixed priority order, where each layer overrides the layers below it. This sequence ensures consistent conflict handling and predictable output across the editor and the front end.

1. WordPress Core Defaults. Baseline fallback values that apply only when no theme or user styles are defined.
2. theme.json: Global Styles. Theme-level styles that override core defaults and establish the base design system for the active theme.
3. theme.json: Block-Specific Styles. Scoped style rules that override the theme’s global styles for individual block types.
4. User Global Styles. User-defined settings saved through the Global Styles interface, overriding all theme-provided styles, both global and block-level.
5. User Block Customizations. The highest-priority layer, representing direct block-level edits made in the editor. These take final precedence over all other style sources.

How to Create Style Variations in WordPress Themes?

Style variations are alternate design configurations created by adding theme.json files to a theme’s styles directory. Each variation file defines a title and slug, then overrides or extends the base theme’s settings and styles values. These variations inherit the theme’s core templates, layout structure, and functional behavior, changing only the design layer—such as color palettes, typography rules, spacing scales, and other visual parameters.

When present, WordPress detects variation files and displays them in the Global Styles panel as selectable design options. Because they modify only settings and styles, variations operate strictly as design-layer overrides without altering templates, blocks, or site structure.

Example variation file:

{
  "title": "Modern Light",
  "slug": "modern-light",
  "settings": {},
  "styles": {}
}

File location:

/wp-content/themes/your-theme/styles/modern-light.json

Difference Between theme.json for Design and for Development

The theme.json file supports two distinct configuration domains that serve different purposes within a WordPress theme:

1. Design Output (styles)

The styles section defines the theme’s visual presentation. It specifies:

• typography rules
• spacing values and scales
• color palettes and gradient definitions
• border properties
• layout constraints
• element-level and block-level appearance settings

These values determine how the theme renders on the front end and within the editor preview.

2. Editor Configuration (settings)

The settings section defines the editor environment and tool availability. It controls:

• which color, typography, spacing, and layout tools appear in the UI
• feature toggles and block-support options
• per-block enablement rules
• restrictions that guide editorial workflows

Although both domains exist in the same file, they operate in separate semantic layers:

• styles defines visual output.

settings defines editor capabilities and configuration logic.