theme.json
A configuration file in WordPress block themes that controls global styles, colors, typography, spacing, and layout settings using JSON format.
The theme.json file is a single configuration file that tells WordPress how your block theme should look and behave. Instead of writing hundreds of lines of CSS and PHP to define colors, fonts, and spacing, you declare them in one structured JSON file at your theme’s root directory. WordPress reads this file and generates the styles, editor settings, and CSS custom properties automatically.
Think of it as the control panel for your entire theme’s design system. One file, one source of truth.
How It Works
WordPress looks for theme.json in your theme’s root folder (e.g., wp-content/themes/your-theme/theme.json). The file follows a specific schema defined by WordPress core. Here is a minimal example that sets a custom color palette and base font size:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"color": {
"palette": [
{ "slug": "primary", "color": "#1a3c6e", "name": "Primary" },
{ "slug": "secondary", "color": "#f5a623", "name": "Secondary" }
],
"custom": false
},
"typography": {
"fontSizes": [
{ "slug": "small", "size": "14px", "name": "Small" },
{ "slug": "regular", "size": "18px", "name": "Regular" }
]
}
},
"styles": {
"color": {
"background": "#ffffff",
"text": "#1a1a1a"
},
"typography": {
"fontSize": "18px",
"lineHeight": "1.6"
}
}
}When WordPress processes this file, it generates CSS custom properties like --wp--preset--color--primary: #1a3c6e and applies your style declarations globally. The settings key controls what options appear in the block editor sidebar. The styles key applies default styles to the front end and editor. Setting "custom": false under color removes the custom color picker from the editor, which keeps clients from going off-brand.
The file uses schema version 3 as of WordPress 6.6+. Version 2 still works but lacks newer features like default font size controls and section styles.
Common Use Cases
Enforcing brand consistency across a client site. Lock the color palette to 4-6 approved brand colors by defining them in theme.json and disabling custom colors. When you hand the site to a client, they pick from your palette instead of choosing hot pink on a whim. In our agency, this cut “can you fix the colors” support tickets by roughly 60%.
Controlling the block editor UI. You can disable specific features globally or per-block. Need to prevent clients from adding drop caps? Set "typography": { "dropCap": false } under settings. Want to restrict border controls to only certain blocks? Use per-block settings. This is the right way to simplify the editing experience without writing PHP filters.
Building child themes with minimal code. A child theme’s theme.json merges with the parent’s file. You can override just the color palette or font stack in a 15-line file instead of duplicating an entire stylesheet. WordPress handles the merge order automatically: core defaults, then parent theme, then child theme.
Creating style variations. Drop alternative JSON files into a styles/ folder (e.g., styles/dark-mode.json) and users can switch the entire site’s look from Appearance > Editor > Styles. Each variation file only needs to declare what differs from the base theme.json.
Why It Matters
Before theme.json, theme developers scattered style logic across functions.php, style.css, editor-style.css, and Customizer callbacks. A single color change could require edits in 3-4 files. That is technical debt waiting to happen.
With theme.json, your design tokens live in one place. WordPress generates 100% of the CSS custom properties from this file, which means fewer style conflicts, smaller CSS output, and faster page loads. In our testing, a well-structured theme.json replaced over 400 lines of legacy CSS in one theme migration.
For site owners, the practical impact is direct: the block editor reflects your real theme styles accurately. No more “it looked different in the editor” problems. The editor and front end share the same generated stylesheet, which eliminates the visual mismatch that plagued classic themes for years.
If you are building or choosing a block theme in 2026, theme.json is not optional. It is the foundation. Skip learning it and you will fight the editor instead of using it.