Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 68 ยท Block Themes and the Site Editor

theme.json

Learn theme.json for WordPress block themes - version 3, settings for color, typography, spacing and layout, global, element and block styles, presets and CSS variables.

theme.json is the control center of a block theme. In one JSON file you declare which colors and font sizes the editor offers, how wide the content column is, which design controls appear in the sidebar, and what the site looks like by default. WordPress reads the file and turns it into CSS for both the front end and the editor, so what you see while editing matches what visitors get.

The file has two main halves: settings (what the editor allows) and styles (what the theme looks like). Settings also create presets: named values such as a color called "primary" that become CSS custom properties and utility classes. This lesson walks through the structure and shows how presets become CSS variables, with plain-PHP stand-ins you can run. The real theme.json examples are read-only, because WordPress cannot run on this site.

If you have not seen block themes yet, read Block Themes: The Big Picture first.

The skeleton

JSON
{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {},
  "styles": {},
  "customTemplates": [],
  "templateParts": []
}
  • $schema gives editors with JSON schema support (such as VS Code) autocomplete and validation. It is optional, but very helpful.
  • version selects the file format. Version 3 is current for new themes (WordPress 6.6 and later); version 2 works from WordPress 5.9. WordPress core fills in anything you leave out, and the format differences between versions are small, mostly about how default presets behave. Pick one version and check the handbook for your WordPress version when you upgrade.
  • settings controls features and defines presets.
  • styles sets default styling.
  • customTemplates and templateParts register extra templates and template-part areas (see Block Templates and Template Parts).

Settings

Settings turn editor features on or off and define the choices the user can pick. A typical block:

JSON
{
  "settings": {
    "appearanceTools": true,
    "layout": {
      "contentSize": "40rem",
      "wideSize": "72rem"
    },
    "color": {
      "defaultPalette": false,
      "palette": [
        { "slug": "base",    "name": "Base",    "color": "#fffaf0" },
        { "slug": "contrast","name": "Contrast","color": "#1f2937" },
        { "slug": "primary", "name": "Primary", "color": "#9a3412" }
      ]
    },
    "typography": {
      "fluid": true,
      "fontFamilies": [
        {
          "slug": "system",
          "name": "System",
          "fontFamily": "system-ui, -apple-system, \"Segoe UI\", sans-serif"
        }
      ],
      "fontSizes": [
        { "slug": "small",  "name": "Small",  "size": "0.875rem" },
        { "slug": "medium", "name": "Medium", "size": "1.125rem" },
        { "slug": "large",  "name": "Large",  "size": "2rem",
          "fluid": { "min": "1.5rem", "max": "2.5rem" } }
      ]
    },
    "spacing": {
      "units": ["rem", "px", "%"],
      "spacingSizes": [
        { "slug": "30", "name": "Small",  "size": "0.75rem" },
        { "slug": "40", "name": "Medium", "size": "1.5rem" },
        { "slug": "50", "name": "Large",  "size": "3rem" }
      ]
    },
    "custom": {
      "lineHeight": { "body": 1.6, "heading": 1.2 },
      "borderRadius": "6px"
    }
  }
}

What each part does:

  • appearanceTools is a shortcut that switches on a group of design controls (border, link color, block gap, margin and padding, line height and more) with a single flag, so you do not enable them one by one.
  • layout sets the width of the default content column (contentSize) and of "wide" blocks (wideSize).
  • color.palette lists the colors the editor offers. defaultPalette: false hides WordPress's built-in colors so users only see yours.
  • typography.fontFamilies and fontSizes define fonts and sizes. With fluid typography enabled, sizes scale smoothly between a minimum and maximum with CSS clamp() (see Style Variations, Fonts and Design Tokens).
  • spacing.spacingSizes is the spacing scale used by padding, margin and gap controls.
  • custom holds free-form values that become CSS variables but get no editor controls.

Presets become CSS custom properties

Every preset you declare generates a CSS variable on the page, following a predictable naming scheme:

Setting Variable
color.palette --wp--preset--color--{slug}
color.gradients --wp--preset--gradient--{slug}
typography.fontFamilies --wp--preset--font-family--{slug}
typography.fontSizes --wp--preset--font-size--{slug}
spacing.spacingSizes --wp--preset--spacing--{slug}
custom (nested keys joined by --) --wp--custom--{key}--{key}
layout.contentSize and wideSize --wp--style--global--content-size and --wp--style--global--wide-size

Camel-case names are turned into kebab-case, so the custom key borderRadius becomes --wp--custom--border-radius. WordPress also generates utility classes for color and font presets, for example .has-primary-color, .has-primary-background-color and .has-large-font-size. These are what the editor attaches to a block when the user picks a preset.

Because the output is plain CSS custom properties, your own stylesheet can use var(--wp--preset--color--primary) anywhere, and a style variation or user customization changes the value for the whole site at once.

flowchart LR
    A["theme.json<br/>settings"] --> B["Presets"]
    B --> C["CSS variables<br/>--wp--preset--*"]
    B --> D["Utility classes<br/>.has-*"]
    A --> E["Editor controls<br/>and options"]
    F["theme.json<br/>styles"] --> G["CSS rules<br/>using the variables"]
    C --> G

Settings declare presets and editor options; styles then use those presets in generated CSS rules.

The example below is a small generator that does what WordPress does with the settings half: it reads the JSON and prints the variables and classes. It is a stand-in, not core's code, and the real output has more rules, but the naming follows the table above.

PHP From theme.json presets to CSS variables

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Styles: global, elements and blocks

The styles section sets how things look. It works at three levels, from broad to specific:

JSON
{
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--contrast)"
    },
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--system)",
      "fontSize": "var(--wp--preset--font-size--medium)",
      "lineHeight": "var(--wp--custom--line-height--body)"
    },
    "spacing": {
      "padding": { "top": "var(--wp--preset--spacing--40)", "bottom": "var(--wp--preset--spacing--40)" }
    },
    "elements": {
      "link": {
        "color": { "text": "var(--wp--preset--color--primary)" },
        ":hover": { "typography": { "textDecoration": "underline" } }
      },
      "heading": {
        "typography": { "lineHeight": "var(--wp--custom--line-height--heading)" }
      }
    },
    "blocks": {
      "core/button": {
        "border": { "radius": "var(--wp--custom--border-radius)" },
        "color": {
          "background": "var(--wp--preset--color--primary)",
          "text": "var(--wp--preset--color--base)"
        }
      }
    }
  }
}
  1. Global styles at the top of styles apply to the whole site (the body and root).
  2. elements style HTML elements: link, heading (or h1 to h6), button, caption, cite. Pseudo states such as :hover go inside the element.
  3. blocks style a specific block by its full name, such as core/button. Blocks can have their own nested elements too.

More specific levels override broader ones. The same structure is used by style variations and by the user's saved styles, which is why merging layers works.

You can write a preset reference in two ways. The long form is a CSS value like var(--wp--preset--color--primary). The short form var:preset|color|primary is what the editor itself saves, and WordPress converts it to the long form when generating CSS. Both are valid inside theme.json.

The generator below resolves references and prints CSS from a styles object. WordPress generates more specific selectors (and wraps them in :where() to keep specificity low); this stand-in keeps them simple so you can see the mapping.

PHP Compiling theme.json styles to CSS

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Notice that the short form var:preset|spacing|40 became var(--wp--preset--spacing--40): the same variable the first generator created from spacingSizes. That connection is what keeps a theme consistent: define a token once in settings, use it everywhere in styles.

Tips for writing theme.json

  • Define presets first and reference them in styles; avoid hard-coded colors and sizes in the styles section.
  • Use the custom section for values that need a variable but no editor control, such as a border radius or an animation duration.
  • Add $schema and validate. A misspelled key is silently ignored by WordPress, which is a frustrating bug to find.
  • Keep custom CSS to a minimum; if something can be expressed in theme.json, users can then override it in the Site Editor.
  • Remember that the user's saved Styles panel changes override your file; test with a clean database as well.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What CSS variable does a palette color with the slug accent generate?

    Palette presets are exposed as --wp--preset--color--{slug}, so accent becomes --wp--preset--color--accent. WordPress also generates .has-accent-color and .has-accent-background-color classes.
  2. 2. In theme.json, what is the difference between settings and styles?

    settings control which features and preset values the editor offers, while styles use those values to set the site's default look.
  3. 3. The custom key borderRadius is declared under settings.custom. Which variable is generated?

    Custom values use the --wp--custom-- prefix and camel-case keys are converted to kebab-case, giving --wp--custom--border-radius. Nested keys are joined with double dashes.
  4. 4. What does the short reference var:preset|color|primary mean inside theme.json styles?

    That short form is the notation the editor stores. WordPress converts it to the CSS variable form, so both forms work.
  5. 5. A block style under styles.blocks overlaps with a global style. Which applies to that block?

    Styles get more specific from global to elements to blocks, and the more specific rule overrides the broader one for that block.

Summary

  • theme.json has a version (use 3 for new themes), settings for options and presets, and styles for the default look.
  • Presets create CSS variables named --wp--preset--{type}--{slug}, plus utility classes such as .has-primary-color.
  • settings.custom creates --wp--custom--* variables, and the layout sizes become --wp--style--global--content-size and --wp--style--global--wide-size.
  • appearanceTools switches on a set of design controls with one flag.
  • styles apply at three levels, global, elements and blocks, and the more specific level wins.
  • Reference presets from styles instead of hard-coding values, and add the $schema line to catch mistakes.

Next, see how templates use these styles and blocks: Block Templates and Template Parts.