Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared Managed Cloud India
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Best lists Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Setup & site building · Guide

theme.json Explained: Colors, Fonts and Spacing

Short answer

theme.json is a JSON file in a theme's root folder that defines its colors, fonts, spacing and editor controls in one place. WordPress turns those values into CSS custom properties and editor choices, so the editor and the front end share the same design tokens. The latest format is version 3, introduced in WordPress 6.6.

Key takeaways

  • theme.json is a JSON file in a theme's root folder that sets colors, fonts, spacing and editor controls in one place.
  • Version 3 is the latest theme.json format, introduced in WordPress 6.6 and still current as of November 2026.
  • Settings decide what editors can choose; styles decide what visitors see.
  • Each palette color creates a CSS custom property and three classes for text, background and border.
  • Slugs are fixed once content uses them, since saved blocks store the class names.

What is theme.json?

theme.json is a JSON file that sets a WordPress theme's colors, fonts, spacing and editor controls in one place.

The Block Editor Handbook describes it as the single point that joins the style APIs into one file. Before theme.json, themes set editor options with scattered theme support flags and custom CSS. The file gives those choices one home, so the editor and the front end read the same values.

theme.json arrived with WordPress 5.8, according to the Block Editor Handbook. The latest format is version 3, which WordPress 6.6 introduced, and it is still the latest version as of November 2026. Older versions keep working, and the handbook notes that new features are built on the latest version.

JSON itself is a plain text format for structured data. MDN defines JSON as a data format that can hold numbers, strings, booleans, null, arrays and objects. That shape is why theme.json uses nested objects: each setting is a named value inside a named group.

Where does theme.json live, and which themes use it?

theme.json sits in the root folder of a theme, next to style.css.

The handbook states the file should be located inside the root of the theme directory. WordPress reads it when the theme loads, in both the editor and the front end. A theme with no theme.json still works, and WordPress falls back to its own defaults.

Block themes rely on theme.json the most, since it defines their global styles. Classic themes can use it too, for editor controls and shared design tokens, while their PHP templates keep rendering pages.

Learn WordPress notes that a theme.json file is required when a block theme is submitted to the WordPress.org theme directory.

If you edit a theme you did not build, use a child theme instead. Editing the parent theme directly means an update can wipe out your file. A child theme keeps your theme.json safe when the parent updates.

Block themes and classic themes differ in how they render pages.

How does theme.json handle colors?

theme.json defines a color palette in settings, then applies colors in styles.

A palette entry has three parts: a slug, a name and a color value. The handbook example uses black (#000000) and white (#ffffff) as the first two entries. Each slug becomes a CSS custom property, such as --wp--preset--color--black, which WordPress prints on the front end and in the editor.

One palette color generates three CSS classes, according to the Block Editor Handbook. Those classes cover text color, background color and border color. The class pattern is .has-{slug}-color, so a color with the slug primary gives editors a “Primary” choice in the color picker.

You can also turn off color choices you do not want. Setting settings.color.custom to false stops editors from picking any color outside the palette. The handbook lists defaultPalette as the switch for the built-in WordPress palette, so you can hide it and show only your brand colors.

Gradients and duotone filters work the same way. Each gradient preset gets one class and one custom property, and the handbook example names presets such as “Blush bordeaux” with a 135-degree linear gradient.

How does theme.json handle fonts?

theme.json defines font families and font sizes as presets under settings.typography.

A font family preset has a slug, a name and a font stack. The handbook example lists a system font stack that starts with -apple-system and BlinkMacSystemFont, then falls back to Segoe UI, Roboto and sans-serif. Each family becomes one CSS custom property, such as --wp--preset--font-family--system-font.

A font size preset has a slug, a name and a size. The handbook example defines “Big” at 32 and “x-large” at 46. Those sizes become classes like .has-big-font-size and custom properties like --wp--preset--font-size--big, so the same size is available in the editor and on the front end.

Fluid typography lets a size grow and shrink with the screen width.

The handbook lists typography.fluid as a setting you can switch on, and Learn WordPress describes the font size presets as part of the settings that shape the editor.

Check headings at phone and desktop widths after you switch it on, since a size that looks right at one width can crowd text at another.

Free and premium themes differ in the font and color choices they ship with.

How does theme.json handle spacing?

theme.json controls spacing with a scale, named sizes and per-side padding and margin.

The spacing scale builds sizes from a starting value with a multiplier. The handbook example uses the * operator, an increment of 1.5, 7 steps, a medium step of 1.5 and a rem unit. WordPress turns that scale into named spacing presets, starting near 0.44rem and rising to about 5.06rem at the top step.

Named spacing sizes are simpler to read. The handbook example names three: “Small” at 1rem, “Medium” at 1.5rem and “Large” at 2rem. Each one becomes a custom property like --wp--preset--spacing--50, which you can reuse in styles instead of typing raw values.

The styles.spacing section applies spacing to the page. It accepts blockGap for the space between blocks, plus margin and padding with top, right, bottom and left values. Layout widths live in settings.layout, where the handbook example sets contentSize to 800px and wideSize to 1000px.

Spacing settingWhere it livesWhat it does
spacingScalesettings.spacingBuilds a size scale from a multiplier
spacingSizessettings.spacingNames fixed sizes such as Small and Large
blockGapstyles.spacingSets the gap between blocks
contentSizesettings.layoutSets the main content width
padding and marginstyles.spacingSets space inside and outside elements

How do settings and styles differ?

Settings decide what editors can choose, and styles decide what visitors see.

The settings object lists the options shown in the editor: the palette, the font sizes, the spacing sizes and which controls are switched on or off. The styles object applies values to the site, such as the body text color, the background color and the gap between blocks.

The handbook shows the split in the file shape itself. A theme.json file holds settings, styles, customTemplates and templateParts side by side, with version at the top.

Settings never paint a pixel on their own; they only offer choices. Styles never add an editor control; they only apply values.

Settings also work per block. Top-level settings apply to every block, and a block entry under settings.blocks can override them. The handbook gives the example of enabling font size controls for all blocks except headings, or giving the Group block its own palette.

The custom field adds your own CSS custom properties. Values under settings.custom become properties named --wp--custom--{name}, such as --wp--custom--line-height--body at 1.7 in the handbook example. Use them for values no preset covers, such as a line height scale.

How do style variations, templates and template parts fit in?

theme.json also records template parts, custom templates and style variations for a theme.

The top-level file can list customTemplates and templateParts, which describe the template files in the theme's folders. Learn WordPress lists those two fields beside settings and styles as the parts of a theme.json file. They are metadata, not styles: they tell WordPress which templates exist and what they are called.

Style variations are separate JSON files that sit beside theme.json. A variation reuses the same settings and styles shape to offer a different look, such as a dark color scheme with the same layout. WordPress lists each variation in the Site Editor, so a site owner can switch looks without changing themes.

The Site Editor is where users change these values without code.

Learn WordPress explains that changes made in the editor are saved as JSON and turned into CSS, and that the theme file is only one level in a loading order.

WordPress core defaults sit at the bottom, the theme file overrides them, and user choices in the editor sit at the top.

Check whether a theme is safe before you install it, since theme.json files can come from any theme author.

How do you check that theme.json works?

Open the Site Editor and the front end after every change, and look for the values you set.

Start with the editor. Open “Appearance” then “Editor”, and open “Styles”.

Your palette colors, font sizes and spacing sizes should appear there with the names you gave them. If a preset is missing, the file has a syntax error or the setting sits in the wrong place.

Next, check the front end. View the page source and search for --wp--preset--.

Your custom properties should be printed in a style block, with values that match your file. A missing property means WordPress did not read that preset, often because a slug or a bracket is wrong.

Validate the JSON before you save it. MDN notes that JSON forbids trailing commas and requires double-quoted property names, and both mistakes break the whole file. Paste the file into a JSON validator, fix the error it reports, then reload the editor.

WordPress 7.1.4 is the latest version as of November 2026, according to the WordPress 7.1.4 release notes. Check your site runs a supported release before you rely on newer theme.json features, since older versions may ignore settings they do not know.

What mistakes should you avoid?

The most common mistakes are bad JSON, changed slugs and settings in the wrong section.

First, never edit theme.json in a live theme without a copy. One missing comma disables the whole file, and WordPress falls back to its defaults with no warning on the front end. Keep the file in version control or save a copy before each edit.

Second, do not rename a palette or font slug after content uses it. Saved blocks store classes like .has-primary-background-color, and renaming the slug leaves those classes with no matching preset. Pick slugs once, then treat them as fixed.

Third, do not put style values in settings or editor controls in styles. Settings only offer choices, and styles only apply values, so a color written under styles never appears in the picker, and a palette written under styles never generates classes.

Fourth, do not turn off controls your editors need. Disabling custom colors or custom font sizes keeps the design tidy, but it also blocks a legitimate one-off change. Switch controls off only when the design system truly has no room for exceptions.

Themes and plugins play different roles, so keep design tokens in the theme and features in plugins.

Frequently asked questions

Can a classic theme use theme.json?

No. Block themes rely on it the most, but classic themes can use theme.json for editor controls and shared design tokens while PHP templates keep rendering pages. The file is required when a block theme is submitted to the WordPress.org theme directory.

Is it safe to edit theme.json in a theme I did not build?

Yes, if you edit the theme.json file in a child theme. Editing the parent theme directly means the next theme update can overwrite your file. Put your copy in the child theme so your settings survive updates.

How do I know WordPress read my theme.json file?

Open the Site Editor under Appearance, then Editor, and check Styles for your palette, font sizes and spacing sizes. Then view the front end page source and search for --wp--preset-- to confirm WordPress printed your custom properties.

Why did my styles disappear after I edited theme.json?

A broken theme.json file usually means invalid JSON, such as a trailing comma or a missing bracket. WordPress falls back to its defaults, so the site still loads but your styles vanish. Paste the file into a JSON validator and fix the error it reports.

Do I have to update an old theme.json file to version 3?

No. Older versions keep working, and WordPress reads them as before. New features are built on version 3, so stay on an older version only if you need its exact behavior, and move to version 3 when you want the newest settings.

Can the Site Editor override theme.json values?

Yes. The theme file sets the defaults, and choices made in the Site Editor sit above it. WordPress core defaults sit below the theme file. That order lets site owners adjust colors and fonts without editing code.

Sources

  1. Global Settings & Styles (theme.json) WordPress Developer Resources
  2. Applying Styles WordPress Developer Resources
  3. Global settings and styles Learn WordPress
  4. JSON - Glossary MDN Web Docs
  5. WordPress 7.1.4 WordPress.org

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

WPLegible editors

Researched from the primary sources listed above and checked against our editorial rules. About the site · How we test