What is the theme.json in WordPress Full Site Editing?

The role of theme.json in shared editor settings and frontend styles, with a valid minimal configuration.

The Site Editor lets you build a block theme’s templates with blocks. The theme.json file configures shared settings and styles, including colours, typography and layout defaults; it is not the file that contains the page’s block structure.


The blueprint of your website

Think of theme.json as the theme’s shared settings and style configuration. Block templates live in templates/*.html and template parts in parts/*.html. Scripts and stylesheets use WordPress’s asset APIs rather than invented scripts or globalStyles JSON fields.

Here’s a minimal example of what a theme.json file might look like:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "layout": {
      "contentSize": "760px",
      "wideSize": "1280px"
    }
  },
  "styles": {
    "color": {
      "background": "#F7F7F2",
      "text": "#161616"
    }
  }
}

This example uses the version 3 configuration format and sets the reading width and text colours. Add only supported settings and styles; validate against the schema for the WordPress version you support.

Resources to learn more

Start with the official theme.json introduction. Test settings in both the editor and frontend.

The Theme Handbook covers block templates, patterns and asset loading.

There are also Full Site Editing examples and templates available on GitHub:

https://github.com/WordPress/gutenberg-examples/

With these resources at your fingertips, you’ll be well on your way to creating beautiful and functional websites with WordPress and the theme.json file!

Frequently asked questions

Does theme.json replace CSS?

No. It configures supported settings and styles; a theme can still use CSS for layouts or details outside those settings.

Does theme.json contain my post template?

No. A block theme stores template markup in its templates directory, and template parts in its parts directory.

Good things, occasionally.

Fresh ideas, useful tools and better ways to build. Delivered when we have something worth sharing.