Open a modern WordPress theme folder and you will find a file that did not exist a few years ago. It sits next to the stylesheet, it is not written in PHP or CSS, and it quietly controls more of your site’s appearance than either of them. That file is theme.json.<\/p>\n
If you have ever wondered why some colour options appear in the editor and others do not, or why a font size you set refuses to stick, this file is usually the reason. Here is what it does, how it is put together, and what to do with it.<\/p>\n
theme.json is a settings file. It tells WordPress two things: what design choices the editor should offer, and what the default styling should be before anyone changes anything.<\/p>\n
It is written in JSON, a plain text format built from labelled values. There is no programming logic in it. No loops, no conditions, no functions. Just a structured list of settings that WordPress reads when it builds a page.<\/p>\n
Think of it as the rulebook a theme hands to the editor. The editor reads the rulebook and shows the user only the options the theme allows.<\/p>\n
Before this file existed, theme styling was scattered. Some settings lived in the stylesheet. Some lived in PHP support declarations. Some lived in the customiser. Some were hard-coded in template files.<\/p>\n
That worked when a theme controlled everything. It stopped working once the editor let people change colours, fonts and spacing directly. Two systems were now setting the same properties, and they argued. The result was a familiar frustration: change a setting, and nothing happens on the front end.<\/p>\n
theme.json pulled those scattered decisions into one place with a defined order of priority. One file, one source of truth, predictable behaviour.<\/p>\n
It sits in the root of the theme folder, alongside style.css. A child theme can have its own copy, and that copy takes priority over the parent’s.<\/p>\n
WordPress itself also ships a version of this file. Core defines a baseline, the theme layers its choices on top, and the user’s own choices sit above both. Nothing is lost, it is simply overridden in a set order.<\/p>\n
Open the file and you will see a small number of top-level keys. Four of them matter most.<\/p>\n
A single number telling WordPress which format the file uses. It lets the format change over time without breaking older themes. You set it once and rarely touch it again.<\/p>\n
This section decides what appears in the editor interface. Which colours are on the palette. Whether custom colours are allowed at all. Which font sizes are offered. Whether padding controls appear on a block.<\/p>\n
Anything switched off here disappears from the editor sidebar. That is the point. A theme can hand editors a tight, curated set of choices instead of a full design toolkit, which is exactly what most content teams want.<\/p>\n
This section applies the actual look. Body text colour, background, link colour, heading sizes, default spacing between blocks. These are the values used when nobody has chosen anything else.<\/p>\n
The key distinction is worth repeating. Settings define what is possible<\/em>. Styles define what is applied<\/em>.<\/p>\n These register the reusable regions of your layout, such as a header or footer, and declare any alternative page templates the theme provides. They tell the site editor what each part is and where it belongs.<\/p>\n Here is the mechanism that makes the whole system work. Every preset you define, whether a colour, a font size or a spacing step, is turned into a CSS custom property automatically.<\/p>\n Define a brand colour once, and WordPress generates a variable for it. That variable is then available to your stylesheet, to individual blocks, and to the editor interface. Change the value in one place and it updates everywhere it was used.<\/p>\n This is why a well-built theme.json reduces stylesheet size dramatically. You stop repeating hex codes and pixel values across dozens of rules. If you have previously wrestled with customising headers using custom code<\/a>, this approach will feel like a considerable simplification.<\/p>\n Fonts are the area where this file saves the most effort. You can register the families a theme offers, load the font files locally rather than pulling them from an outside service, and define a fixed scale of sizes with friendly labels such as small, medium and large.<\/p>\n Editors then pick a size by name instead of typing a number. That single change keeps a site visually consistent, because nobody can invent a stray value that fits nowhere in the design.<\/p>\n There is also a fluid option. Set a minimum and a maximum for a size and WordPress will scale it smoothly between them as the screen width changes. Headings shrink sensibly on a phone and grow on a wide monitor without a single media query. It is one of the quiet wins that make the file worth learning.<\/p>\n Two layout values do a surprising amount of work: the standard content width and the wide width.<\/p>\n The first sets how wide a normal block of text should be. The second sets how far a block may stretch when someone chooses the wide alignment option. Define both, and alignment controls start behaving consistently across every page.<\/p>\n Without them, wide and full alignment options either vanish or produce unpredictable results. It is one of the most common causes of layout complaints from editors who cannot understand why a button looks different on two pages.<\/p>\n Settings and styles can be applied globally, or narrowed to a single block type. That flexibility is what makes the file genuinely useful rather than merely tidy.<\/p>\n You might allow custom colours everywhere except in the button block, so buttons stay on brand. You might give the quote block extra padding without touching anything else. You might restrict heading sizes to a fixed scale while leaving paragraph text free.<\/p>\n Each block simply gets its own entry, nested under the relevant section. The syntax is the same, only the scope changes.<\/p>\n Element styling works in a similar way. Links, buttons, headings and captions can each be targeted on their own, so a link colour set once applies across the whole site without you hunting through a stylesheet for stray rules.<\/p>\n When several sources define the same property, WordPress resolves them in a fixed order. Understanding this order removes almost all of the confusion around styling.<\/p>\n So if a value refuses to change, the answer is usually that something further up the stack has already claimed it. Work down the list and you will find it.<\/p>\n theme.json handles design tokens and defaults. It does not handle everything.<\/p>\n Complex selectors, animations, media queries and hover states still belong in a stylesheet. PHP still handles template logic, custom functions and integrations. Plugin behaviour is untouched by it.<\/p>\n Classic themes can also use a limited version of the file to define palettes and font sizes, even without full site editing. They will not get the layout and template features, but the editor still reads the presets. Anyone still running the older editing experience, perhaps after choosing to keep the classic editor<\/a>, will see far less benefit from it.<\/p>\n A few habits prevent most of the pain.<\/p>\n Never edit a parent theme directly.<\/strong> Updates overwrite it. Put your version in a child theme instead. Our explanation of how WordPress themes work<\/a> covers why this matters.<\/p>\n Validate before uploading.<\/strong> JSON is strict. One trailing comma or one missing bracket and the file fails to parse. WordPress falls back to defaults, and your site suddenly looks wrong everywhere at once. A free online validator catches this in seconds.<\/p>\n Back up first.<\/strong> Keep a copy of the working file before you change it. It is a small file and a fast restore.<\/p>\n Change one thing at a time.<\/strong> Adjust a value, reload, look. Batch edits make it far harder to identify which change caused a problem.<\/p>\n The most common error is confusing the two main sections. Adding a colour to settings makes it appear in the picker. It does not apply it anywhere. To use it as a default, you also need an entry in styles.<\/p>\n The second is forgetting the version number, which can cause WordPress to misread the whole file.<\/p>\n The third is over-restriction. Turning off every custom option feels tidy, but editors then find they cannot make the small adjustment a page genuinely needs, and they come to you instead. Aim for a curated set, not a locked cage.<\/p>\n The fourth is caching. If a change does not appear, clear your caching layer and any browser cache before assuming the file is wrong. Style output is cached, and stale CSS causes plenty of false alarms. The same principle applies to a range of common block editor problems<\/a>.<\/p>\n If you use a well-built theme and never touch its files, you can happily ignore it. The site editor gives you a visual interface over the same values.<\/p>\n If you build or customise themes, it is no longer optional. It is the standard place design decisions live in modern WordPress, and working around it usually creates more problems than it solves.<\/p>\n And if you are somewhere in the middle, running a business site and occasionally wanting a change your theme will not allow, knowing the file exists is enough. You now know what to ask for.<\/p>\n Find the file in your active theme and read it. Even without editing anything, seeing your site’s colours and sizes written out as a short list of values makes the design system click in a way that browsing the interface rarely does.<\/p>\n Then, in a staging copy, change one colour value and reload. Watching a single edit ripple across the whole site is the fastest way to understand what this file is for.<\/p>\ntemplateParts and customTemplates<\/h3>\n
Presets Become CSS Variables<\/h2>\n
Typography Gets Special Treatment<\/h2>\n
Layout Without Guesswork<\/h2>\n
Per-Block Control<\/h2>\n
How the Layers Stack<\/h2>\n
\n
What It Does Not Replace<\/h2>\n
Editing It Safely<\/h2>\n
Mistakes Worth Avoiding<\/h2>\n
Do You Actually Need to Learn It?<\/h2>\n
Where to Start<\/h2>\n