theme.json

theme.json — is a mechanism for configuring the block editor and block themes that affects both the front end and the back end. It was created to provide standardized (canonical) control over block settings.

The introduction of blocks increased the number of settings developers and users need and don’t need — this became a problem, so the theme.json file was created: a single configuration point.

All possible theme.json file settings.

Also read: Synchronizing site styles with theme.json

Child theme

  • If the child theme doesn’t have a theme.json, WordPress uses the parent theme.json.

  • If the child theme has a theme.json, WordPress merges both files: values from the child override identically named values, and everything that isn’t set is inherited from the parent.

More details here: https://fullsiteediting.com/lessons/child-themes/

Settings for individual blocks

With theme.json, you can control settings at the level of individual blocks.

Examples of what you can achieve:

  • Use a specific preset for a block (e.g., tables), but shared with other blocks.

  • Enable a UI control for font size for all blocks except the headings block.

  • and so on.

How to connect the theme.json file?

For the theme.json file to start working, it needs to be created in the theme folder.

If the theme has no theme.json file, the default file wp-includes/theme.json is used.

Where modified styles are stored

When editing style settings in the site editor, the database stores the difference compared to the theme.json of the theme.

These changes are saved to the wp_posts table in post_type = wp_global_styles. Such a record can be one per theme.

Important fields:

  • post_content — stores the JSON of modified styles. This JSON is merged with the data from theme.json.
  • post_name — stores a slug pointing to the theme whose styles they belong to. The template is: wp-global-styles-{theme_folder_name}. This is needed because different themes may have different styles.

For example, if you need to save (export) the current styles, then you can save the content from this wp_posts.

Gutenberg plugin

theme.json is read by both the WordPress core and the Gutenberg plugin. The difference is that:

  • Core — contains a stable, already accepted theme.json schema for releases.
  • Gutenberg plugin — the “nightly” build of the editor. It introduces new/experimental theme.json fields, blocks, and APIs before they become part of the core. Developers install the plugin to test the latest features or use them on older WP versions (< 5.8).

That means the plugin is not required — it simply provides access to features earlier than they become part of the core.

Links: