theme.json or add_theme_support generator

Values to submit

Theme.json give you hability to manage:

  • Settings: default settings apply to all blocks (except for Background), you can override them on a per-block basis (per-block basis presets are not available yet in this theme.json generator).
  • Styles: apply design to website like typography, colors etc. Styles can be applied to body, and in more granular way to specific blocks or elements
  • Custom templates
  • Template Parts: Blocks for any part across the website, excluding the content area.

NB: WordPress Core provides its default settings in its theme.json file, you can view them in /wp-includes/theme.json
That's why sometimes you will need to disable or enable some features.

In theme.json v2, setting appearanceTools true opts-in to the following settings that are false by default:

  • background: backgroundImage (new WP6.4)
  • border: color, radius, style, width
  • color: link
  • dimensions: minHeight
  • position: sticky
  • spacing: blockGap, margin, padding
  • typography: lineHeight

Read more on Block Editor HandBook: Opt-in into UI controls and Developer Resources Appearance Tools

(NB: After enable, avoid duplication with other options on this page)

While using this theme.json Generator for Styles, you can also check the Editor Handbook for Styles to understand where styles can be used

Styles Color

The styles you add here are declared at the top-level.
Styles found at the top-level will be enqueued using the body selector.

body {
  background: var(--wp--preset--gradient--linear-primary-to-secondary);
  background-color: var(--wp--preset--color--primary);
  color: var(--wp--preset--color--secondary);

I advice you to use settings.color.palette and settings.color.gradients first, then add your color slugs. Prefixe are already adjusted.
Alternatively, you can use the default colors built-in to the WordPress Core


Styles Border

The generator here will add borders at the top level so for body element, but pretty much usefull if added on Blocks

Under Construction ! To be continued ...

Custom Templates

In classic theme, to add a custom template, you had to create a file, for example featured-image-cover-block.php and at the top of the file add a comment PHP that states the template’s name, and eventually the Post Type support:

Template Name: Featured image coverblock
Template Post Type: post, page, event

In FSE Theme, you can declare your custom templates directly in theme.json and add your template in the theme "templates" folder.
NB: in FSE theme, this is an html file featured-image-cover-block.html

Choosing custom template in wordpress editor
Custom Templates

Templates Parts

What are Template Parts ?

Block template parts serve the purpose of enabling the editing of any section of a website that lies outside the content area of a post or page, using blocks.
They provide a means to make various elements editable and customizable, including but not limited to the site header, site footer.

You can use it for exemple for site-wide call-to-action (CTA) displayed at the bottom of any page.


Create a new Template part in the Site Editor

  • Edit Site > Template Parts > Manage all template parts
  • Use Button "Add New"
  • Give it a name here we call it "CTA Main"
  • Choose "General", it's not either Header or Footer
  • Create
  • Add all blocks you need
  • Save it

Call it in your "templates files" stored in "templates" folder using this markup in home.html for exemple:

<!-- wp:template-part {"slug":"cta-main","tagName":"section"} /-->

Notice it's similar to Header and Footer, excepted you choose the tagName of your choice, : div, section, p ...

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Refresh you home Page and tada! the block is there!

Now it's time to register this template part for good in your FSE Theme, you will declare it in your "theme.json", add the html file for it in "parts" folder and add the markup in the template of your choice

Template Parts

NB: The available areas are header, footer, and uncategorized.

Snippets Generated

theme.json for WP 5.9 and above, tested up to 6.4.1

By creating a theme.json file in the theme’s top-level directory, themes can configure the existing editor settings. This new mechanism aims to take over and consolidate all the various add_theme_support calls that were previously required for controlling the editor.

Adding "$schema"

I suggest you to use schema in your theme.json, it helps you building block based themes. Used by code editor it provides things like tooltips, autocomplete, and validation while editing. Readmore about it on "Make WordPress"

/* nothing yet... */


The old way to add custom properties to block editor. It continues to be functional for backwards compatibility.
Have a look to Theme Support Guidelines.
Read More about Equivalence add_theme_support in theme.json


WordPress Development Reference for Block Color Palettes

/* nothing yet... */


Themes are responsible for creating the classes that apply to palette, gradients or fonts

/* nothing yet... */


If you use Sass you can generate your css classes like this

/* nothing yet... */