What Is theme.json in WordPress? A Beginner’s Guide

If you’ve started exploring block themes for WordPress, you’ve probably come across a file called theme.json. At first glance, it looks like a simple configuration file. But it controls a lot — from color palettes and font sizes to how the block editor behaves for your entire site.

This guide explains what theme.json is, how it works, and how to start using it in your own themes. No prior experience with it is required. By the end, you’ll understand the core concepts well enough to read and write a theme.json file with confidence.

What Is theme.json?

theme.json is a JSON configuration file that lives in the root folder of your WordPress theme. It lets you define global settings and styles for your site — things like color palettes, font families, spacing sizes, and content layout widths.

JSON stands for JavaScript Object Notation. It’s a plain-text format for storing structured data using labels and values. You don’t need to know JavaScript to use it. It reads like an organized list of settings.

Think of theme.json as a design control panel for your theme. Instead of scattering style decisions across multiple PHP files and CSS stylesheets, you define them in one place. WordPress reads this file and applies your settings to both the front end of your site and the block editor.

theme.json works with both classic and block themes. But it’s particularly important for block themes, where it acts as the foundation of the entire design system.

Why Does theme.json Matter?

Before theme.json, WordPress themes configured editor settings through PHP functions in functions.php. For example, you’d call add_theme_support( 'editor-color-palette', [...] ) to register custom colors. Each theme did things differently, and plugins had no standard way to know what fonts or colors a theme used.

theme.json introduced a shared language between WordPress core, themes, plugins, and users. When you define a color palette in theme.json, the block editor shows those exact colors in the color picker. When you define font sizes, the editor toolbar reflects them. When you set a content width, WordPress applies it sitewide.

Here is what theme.json gives you:

• One place to define your theme’s colors, fonts, and spacing
• Control over which editor controls users can access
• Automatic generation of CSS custom properties from your presets
• Global default styles for the entire site
• Block-level styles that target individual block types
• A live connection between your design tokens and the WordPress editor

Where Does theme.json Live?

Create the file in the root folder of your theme. If your theme folder is called my-theme, the file path would be:

wp-content/themes/my-theme/theme.json

You create this file manually. WordPress detects it automatically when your theme is active.