How to add a custom template to a block theme

Block themes define template in the theme.json file found at the theme root. The “customTemplates” object is a top-level definition found in the theme.json file. It’s purpose is to list every custom template that will be provided by the theme and available to edit using the Site Editor (aka Full Site Editor).

To add a custom template to an existing block theme open the theme.json file and find the customTemplates object definition. Simply copy an existing item, paste in the template definition and edit it as required. If the customTemplates object definition does not exist, you can add it. A WordPress base them such as TwentyTwentyTwo can be used to find the format required.

Example of a single post template defined under “customTemplates” in theme.json. The “postTypes” array specifies that this template should be applied only for the “property” custom post type.

Adding the Template HTML File

With WordPress site editing using Gutenberg, the template files are HTML files with the .html extension. Most block themes will have a directory titled “templates” used for full page and post templates, as well as a “parts” directory for template parts.

The filename (without extension) should match what you’ve defined under the customTemplates object definition in theme.json. If your template is defined as “single-property” as in our example above, then the filename under the templates directory should be exactly single-property.html. The path relative to the theme root then becomes:


With your custom template defined in theme.json and an empty file stored at single-property.html you should now see the custom template listed under the “Templates” page when you open the WordPress Site Editor.

WordPress site editor custom template for how to add a custom template using theme.json.