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 →Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
theme.json is a JSON configuration file in a WordPress theme. It lets theme developers define editor settings and presets, theme styles for the site and its blocks, and some theme metadata. WordPress can use those declarations in both the front end and supported editor interfaces, including the Site Editor’s Styles panel. It is not a plugin or a visual theme editor: it is a structured way to describe design choices that WordPress and users can work with.
What does theme.json do?
The file connects a theme’s design system to WordPress. Its settings section determines which supported controls and presets are available in the editor; its styles section defines how the site, elements, or individual blocks should look. For example, a theme can offer a color palette and apply one of those colors to the site’s text or buttons.
WordPress supports theme.json in block and classic themes, though it is foundational to block-theme development. The structured settings and styles are useful for standard WordPress features because they can be reflected in the editor as well as on the site. They do not replace CSS: traditional stylesheets and custom CSS are still needed for some designs and properties. See the WordPress Introduction to theme.json.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWhat belongs in the file?
The official reference describes these top-level properties. Their availability and details can depend on the WordPress version and schema you target.
$schema: An optional JSON Schema URL that compatible code editors can use for completion, hints, and validation.version: An integer identifying thetheme.jsonformat. It is not the WordPress software version.settings: Controls supported editor options and presets, including areas such as color, typography, spacing, layout, and shadows. Settings can also be scoped to blocks.styles: Sets supported design rules for the site as a whole, elements such as text or buttons, and individual blocks.customTemplatesandtemplateParts: Metadata for custom templates and template parts in the theme’s relevant directories.patterns: An array of pattern slugs, including patterns registered from the WordPress Pattern Directory.
For the property definitions and current supported options, consult the Theme.json Reference.
How do settings and styles differ?
Use settings to choose which controls users can access and which design tokens or presets the theme offers. Use styles to apply the appearance. A palette is a setting; assigning a palette color to the site’s background or to a button is a style. This distinction helps keep editor options intentional rather than exposing controls the design does not need.
Rank #2
Styles can be global defaults or target a particular element or block. Use a global rule when it should apply broadly, and a more specific rule when an element or block needs a different treatment. WordPress recommends using the standard styles property for standard WordPress features where possible: compatible theme styles can be exposed in Appearance > Editor > Styles, and this approach avoids some CSS specificity problems. It does not guarantee that every custom design can be expressed there. The Applying Styles guide explains the supported scopes and how styles are applied.
Which version should you use?
As of September 30, 2026, WordPress Developer Resources identifies schema version 3 as the latest in its Theme.json Reference, last updated September 4, 2026. Some overview or older handbook examples still show version 2. Treat those as examples for their context, not as proof that version 2 is the current default.
Rank #3
Choose the format and properties based on the oldest WordPress release your theme supports. The developer guide lists versioned schema URLs by WordPress release and recommends using the schema for the oldest supported release, which helps avoid introducing settings unavailable to some users. A schema URL is for editor assistance; it does not itself make an unsupported property work in an older WordPress installation. Check the Global Settings & Styles guide and the version-specific reference when adding or migrating properties.
How do you start using theme.json?
- Set the compatibility floor. Decide which WordPress releases the theme must support before choosing a schema format or properties.
- Create the file in the theme. Add
theme.jsonto the theme and include a$schemaURL appropriate to that compatibility target plus an explicitversion. A versioned schema URL can provide editor hints and validation when your editor supports JSON Schema. - Add only needed settings. Start with the controls and presets your theme actually intends to support, such as selected color, typography, spacing, or layout options.
- Apply design rules in styles. Choose global, element, or block scope according to where the rule belongs; more specific rules can override global defaults.
- Validate and preview. Use a JSON Schema-capable editor to catch structural issues, then inspect both the front end and relevant WordPress editor views. The final result may differ when users have customized supported styles.
This example shows the shape of the file, not a recommended compatibility target. The WordPress 6.6 schema URL is illustrative only; select a schema and format that match the theme’s minimum supported WordPress release.
{
"$schema": "https://schemas.wp.org/wp/6.6/theme.json",
"version": 3,
"settings": {},
"styles": {},
"customTemplates": {},
"templateParts": {},
"patterns": []
}Why might a theme.json value not take effect?
A theme’s declarations are one layer in WordPress’s configuration precedence. The documented order runs from core defaults to the theme’s theme.json, then a child theme’s theme.json, and finally user customization saved from the Site Editor. Server-side filters can also modify values. As a result, a theme should not assume its own value always wins. When diagnosing a mismatch, inspect the active child theme, saved user styles, filters, JSON syntax, and compatibility of the property with the installed WordPress version. See Global Settings and Styles.
Within styles, global rules establish defaults while element- and block-specific rules can be more specific. Checking both editor and front-end output helps reveal whether the scope is too broad or an override is taking effect.
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.
