theme.json Explained: Settings, Styles and Presets in WordPress

theme.json is a configuration file in a WordPress theme that controls two things: which design options editors see in the block editor and Site Editor (settings), and how the site looks by default (styles). It defines your color palette, font sizes, spacing scale, layout widths and per-block defaults in one place, and WordPress turns those values into CSS custom properties and editor controls automatically.

WordPress introduced theme.json in version 5.8 (2021). The current schema is version 3, which works with WordPress 6.6 or later. As of October 2026, with WordPress 7.1.2 current, theme.json works with both block themes and classic themes, so it is relevant whether you are building a new block theme or tidying up an older classic one.

This guide is for developers and technically minded site owners. It explains the structure of the file, how presets work, real examples you can adapt, how version 3 changed defaults, and the mistakes that cause most theme.json bugs.

What theme.json does

Before theme.json, a theme configured the editor through a scatter of add_theme_support() calls, editor stylesheets and custom CSS. The Make WordPress Core post introducing the file in 5.8 described the problem it solves: "the conflicts that appear in an environment with core, theme, and user styles as well as the wide design area that comes with multiple blocks." theme.json gives those three layers a shared, structured format.

In practice, theme.json lets you:

• define brand colors, gradients, duotones, font families, font sizes, spacing sizes and shadows as presets,
• turn editor controls on or off globally or per block (for example, no custom colors, or no font-size control on buttons),
• set default styles for the whole site, for HTML elements such as links, buttons and headings, and for individual blocks,
• set content and wide layout widths,
• register custom templates and template parts, and bundle patterns from the Pattern Directory.

When a user changes colors or fonts in the Site Editor's Styles panel, WordPress stores those choices as a user layer on top of the theme's theme.json. That is why a theme can let editors customize within limits rather than with free rein. Our Site Editor guide covers the user side.

The structure of the file

A theme.json file lives in the root of the theme. The top-level keys in the version 3 reference are:

The smallest valid file is just a version number. A practical starting point looks like this: { "$schema": "https://schemas.wp.org/trunk/theme.json", "version": 3, "settings": { }, "styles": { } }. The WordPress theme handbook calls the $schema line "highly recommended" because it gives "on-the-fly hints and error reporting in many code editors."

Settings: what editors are allowed to do

The settings object holds presets and feature toggles. The version 3 reference groups them into sections including appearanceTools, background, border, color, dimensions, layout, lightbox, position, shadow, spacing, typography and custom, plus a blocks object for per-block overrides.

appearanceTools

The handbook describes appearanceTools as "a catchall setting for enabling multiple other settings." Setting it to true switches on a group of design controls (such as border, spacing and related options) in one line, which is convenient for a starter theme. For tightly branded client sites, many developers prefer to leave it off and enable only the controls they want.

Color

A palette is a list of objects with a slug, a color value and a name. Example: "settings": { "color": { "palette": [ { "slug": "base", "color": "#ffffff", "name": "Base" }, { "slug": "contrast", "color": "#111111", "name": "Contrast" }, { "slug": "accent", "color": "#0a6cff", "name": "Accent" } ] } }. The handbook notes that "base" (background) and "contrast" (text) are de facto standard slugs that help content move between themes.

Useful color switches include custom (whether users can pick any color), defaultPalette (whether WordPress's built-in palette appears), defaultGradients and customGradient. To keep editors on brand, set custom to false and defaultPalette to false, so only your palette appears.

Typography, spacing and layout

Typography presets cover font families and font sizes (including fluid sizes). Spacing presets define a scale (for example small, medium, large) used for padding, margin and block gaps. The layout section sets contentSize and wideSize, which control how wide normal and "wide" aligned content can be.

Per-block settings and custom values

Inside settings.blocks you can override any setting for one block type, for example letting only the Heading block use a special display font, or removing the color controls from the Button block. The custom object is, in the handbook's words, "an object for adding custom settings, which are output as CSS custom properties." Values you put there become variables prefixed --wp--custom--, which is handy for things like a shared border radius or header height.

Presets and the CSS they generate

Every preset becomes a CSS custom property using the pattern --wp--preset--{type}--{slug}. A color with the slug contrast becomes --wp--preset--color--contrast. WordPress also generates classes such as .has-contrast-color and .has-contrast-background-color, which the editor writes into your content when someone picks that color.

Inside theme.json styles, reference presets with WordPress's own syntax: "color": { "text": "var:preset|color|contrast" }. The handbook says this syntax "works much better and always appears correctly throughout the interface in the WordPress admin. Save the CSS syntax for when you are actually writing CSS." In a stylesheet, you would write color: var(--wp--preset--color--contrast).

The practical consequence: preset slugs are a contract. Posts store classes like has-accent-color. If you rename the accent slug to brand, existing content still asks for has-accent-color and quietly loses its color.

Styles: the default look

The styles object, according to the handbook, "lets you configure settings at the global level, for individual elements, and individual blocks." It has three layers:

• Top level: site-wide color, typography and spacing, for example "styles": { "color": { "background": "var:preset|color|base", "text": "var:preset|color|contrast" } }.
• styles.elements: HTML elements such as link, button, heading and h1 to h6, for example "elements": { "link": { "color": { "text": "var:preset|color|accent" } } }.
• styles.blocks: individual blocks by name, for example "blocks": { "core/quote": { "typography": { "fontStyle": "italic" } } }.

Style variations, stored as separate JSON files in the theme's styles folder, let a single theme offer alternative palettes and typography that users can switch between in the Site Editor.

Versions 1, 2 and 3: what changed

theme.json has gone through three schema versions. Older version numbers are still accepted (some handbook examples still use version 2), but the living reference and new features assume version 3.

The version 3 change trips people up. According to the official migration guide, when defaultFontSizes is true WordPress shows its default font sizes and prevents the theme from overriding them, and defaultSpacingSizes is true by default after switching to version 3. If your custom font sizes or spacing scale "disappear" or collide with core values after you bump the version number, set those two options explicitly. Read the theme.json migration guide before upgrading an existing theme, and keep the version 3 reference open while you work.

Using theme.json in a classic theme

The handbook states plainly that the file "works with both block and classic themes." For a classic theme, adding theme.json is the lowest-risk way to modernize:

1. Start with version, $schema and a settings.color.palette that matches your existing brand CSS.
2. Add font sizes and a spacing scale, and turn off custom colors and the default palette.
3. Test the block editor: the color picker should now show only your brand colors.
4. Check the front end carefully, because theme.json styles and layout settings can change spacing and widths on existing pages.

If you are building a theme from scratch, our walkthrough on developing a custom WordPress theme covers the surrounding pieces, and block themes vs classic themes explains the hybrid approach.

Common theme.json mistakes

• Invalid JSON. A trailing comma or a missing quote can stop the whole file from being applied. Use the $schema line and a JSON linter.
• Wrong or missing version. Copying a version 2 snippet into a version 3 file (or the reverse) can change how defaults behave.
• Renaming preset slugs. Existing content references slugs through classes; renaming breaks colors and sizes on old posts.
• Using CSS var() syntax in styles. It works, but the WordPress var:preset syntax displays correctly in the admin interface.
• Enabling everything. appearanceTools plus custom colors plus custom font sizes gives editors enough rope to break brand consistency.
• Fighting theme.json with CSS. Heavy !important overrides in style.css make Global Styles appear broken to editors. Move design decisions into theme.json instead.
• Ignoring user customizations. If a client changed colors in the Site Editor, editing theme.json may seem to "do nothing," because the user layer sits on top. Check Styles and reset if needed.

Performance and accessibility notes

Moving design decisions into theme.json can let you retire chunks of hand-written CSS, but a lighter site is not automatic. Keep the number of font families and weights small, avoid loading fonts you do not use, and check Core Web Vitals after changes; our guide to Core Web Vitals on WordPress explains what to measure.

For accessibility, choose palette pairs with sufficient contrast before you ship, since editors will combine your presets freely. Restricting the palette to tested combinations is one of the easiest ways to keep a site accessible as content grows.

Conclusion

theme.json turns a theme's design system into one structured file: settings decide what editors can do, styles decide how the site looks, and presets tie both to stable CSS variables. Use version 3, add the $schema line, treat slugs as permanent and keep design decisions out of ad hoc CSS. For more developer and owner guides, see the WordPress resource hub. If you need a theme built or refactored around theme.json, eSEOspace offers WordPress development services.

Frequently asked questions