theme.json is a JSON configuration file in a WordPress theme. It lets theme authors define editor settings, design presets, global styles, block-specific styles, and selected theme metadata in a structured format. WordPress can use those declarations in both the Site Editor and the rendered site, while site owners can still customize supported options.
It works with block and classic themes, although it is central to modern block-theme development. It complements CSS rather than making CSS unnecessary.
What belongs in theme.json?
WordPress documents theme.json as the place to define global settings, styles, and related theme configuration. The main top-level properties are:
| Property | Purpose |
|---|---|
$schema |
An optional JSON Schema URL that enables completion, hints, and validation in compatible editors. |
version |
The integer identifying the theme.json schema/API format. This is not the WordPress software version. |
settings |
Controls editor options and presets, including color, typography, spacing, layout, shadows, and per-block settings. |
styles |
Defines appearance globally, for elements, and for individual blocks. |
customTemplates |
Describes custom templates supplied by the theme. |
templateParts |
Describes reusable template parts supplied by the theme. |
patterns |
An array of pattern slugs that the theme registers from the WordPress Pattern Directory. |
See the Introduction to theme.json and the Theme.json Reference for the complete property reference.
How settings and styles differ
settings: decide what users can use
Use settings to enable or disable editor controls and to define design tokens such as a color palette, font sizes, spacing presets, layout widths, or shadow options. Settings can also be scoped to a particular block. For example, a theme can expose a constrained set of colors for all blocks while enabling a special option only for the Button block.
styles: define the appearance
Use styles to apply the actual design rules. A style can target the global root, a supported element such as headings or links, or a specific block. Global rules provide defaults; more specific element and block rules can override them. WordPress recommends the standard styles property for features that core supports because those choices integrate with Appearance > Editor > Styles and avoid some CSS-specificity problems. Traditional stylesheets and custom CSS are still appropriate for rules that the structured system does not cover.
Rank #2
The distinction is practical: a palette entry belongs in settings; assigning a background color to the site, a button, or a paragraph belongs in styles. The Applying Styles guide explains the supported scopes and behavior.
A safe starting file
Start with a minimal valid document, then add only the features your theme needs:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Rank #3
{
"$schema": "https://schemas.wp.org/wp/6.6/theme.json",
"version": 3,
"settings": {},
"styles": {},
"customTemplates": {},
"templateParts": {},
"patterns": []
}The URL above illustrates a versioned schema path; it is not a recommendation that every theme target WordPress 6.6. Select the schema corresponding to the oldest WordPress release your theme supports, and use the schema version that release can handle.
Which theme.json version should you choose?
As of September 30, 2026, WordPress Developer Resources identifies schema version 3 as the latest on its Theme.json Reference (page updated September 4, 2026). Older handbook examples may show version 2; do not copy that value blindly into a new theme.
The version number describes the theme.json format, not the installed WordPress version. Compatibility is determined by the oldest WordPress release your project promises to support. Newer schema properties can fail or be ignored on older installations, so consult the version-specific reference and migration guidance before upgrading an existing file.
How to use theme.json step by step
- Set the compatibility floor. Write down the oldest WordPress version the theme must support. That floor determines which schema URL and properties are safe.
- Configure editor validation. Add a
$schemaURL for that compatibility target and an explicit integerversion. A JSON-aware editor can then report syntax and schema errors. - Add required settings. Enable only the appearance controls and presets the theme intends to support. Keep the palette, typography scale, spacing, and layout options deliberate rather than exposing every available control.
- Apply styles at the right scope. Put site-wide defaults in the root styles, shared semantic rules under elements, and exceptions under the relevant block. Use the narrowest scope that expresses the design intent.
- Check metadata paths. If the theme supplies custom templates or template parts, describe them in
customTemplatesortemplatePartsaccording to the current reference. Add pattern slugs topatternsonly when those patterns are actually registered. - Preview both surfaces. Test the front end and the corresponding editor or Site Editor Styles panel. Confirm that presets appear, styles render, and editing a supported option produces the expected result.
The official workflow and property details are covered in Global Settings & Styles (theme.json).
Why a declared value may not win
A theme declaration is one layer in WordPress’s cascade. From lower to higher priority, WordPress combines core defaults, the active theme’s theme.json, a child theme’s theme.json, and user customizations saved from the Site Editor. Server-side filter hooks can also alter the result. Consequently, a theme cannot guarantee that its setting will remain unchanged on every site.
When a value seems missing or overridden, check these in order:
- JSON syntax and whether the property is supported by the selected schema and WordPress version.
- Whether a child theme is active and has its own
theme.json. - Saved user styles in Appearance > Editor > Styles.
- Plugins or theme code using filter hooks to modify global settings or styles.
- Whether a more specific element or block rule overrides the global rule.
WordPress describes this precedence in Global Settings and Styles.
When theme.json is not enough
Use theme.json for standard WordPress settings and styles that should be exposed to users and represented consistently in the editor and front end. Keep a stylesheet or custom CSS for unsupported properties, complex selectors, browser-specific behavior, or design details that should not become user-facing editor controls. The goal is not to move every line of CSS into JSON; it is to express the theme’s WordPress-integrated design system in the format core understands.
Practical compatibility checklist
- Identify the minimum WordPress version before choosing a schema.
- Use the current version-specific reference rather than an undated snippet.
- Keep
$schemaandversionexplicit. - Validate JSON in an editor that supports JSON Schema.
- Separate user-facing controls in
settingsfrom visual rules instyles. - Test with the active parent theme, any child theme, and saved Site Editor customizations.
- Verify both editor output and front-end output before shipping.
The Bottom Line
theme.json is the structured bridge between a WordPress theme’s design system, the Site Editor, and the rendered site. Choose its schema for your oldest supported WordPress release, use settings for controls and presets, use styles for appearance, and remember that child themes, users, and filters can override theme defaults.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
