The theme.json file is nothing but a settings file that tells WordPress how a theme should look and which design options to show in the editor. It was introduced in WordPress 5.8, and every block theme relies on it.
If you want to change your site's colors, fonts or content width in a clean way, this is the file to know.
What does theme.json control?
Think of theme.json as the control panel of your theme's design. It is written in JSON, a simple format of names and values. Here are the main things it handles:
- Color palette: The colors you see when you pick a text or background color.
- Typography: The font families and font sizes available in the editor.
- Layout: The width of normal and wide content, for example
"contentSize": "650px". - Spacing: Padding, margins and the gaps between blocks.
- Block styles: Default styles for individual blocks, such as buttons or headings.
How does theme.json work?
The file has two main sections. settings decides which options appear in the editor, and styles decides how things actually look. For example, you can hide the custom color picker so that writers use only your brand colors.
WordPress combines three layers: its own defaults, your theme's theme.json and the changes you make in the Styles panel of the Site Editor. Your own Styles changes win over the file.
Where can you find theme.json?
It sits in the main folder of your theme, next to style.css. You can download it through FTP and open it in any code editor. Classic themes can use a theme.json file too. A child theme can also have its own theme.json, which overrides matching values from the parent.
If you want to go deeper, start with our theme development overview.
Make your changes in a child theme, not the parent. Also, a small typo like a missing comma can stop WordPress from reading the whole file, so check it carefully.
In a nutshell, theme.json keeps your theme's design settings in one tidy place. That's all for now. If you have any doubts about theme.json, leave them in the comment box below.