Explainer: The `customTemplates` Property in `theme.json`

In Full Site Editing, your theme's templates/ directory contains the HTML files that structure your site (e.g., page.html, single.html). But what if you want to create a special, one-off layout that a user can select from a dropdown menu?

This is the job of the customTemplates property in theme.json. It makes your file-based templates discoverable within the Page and Post editor.

1. The Real-World Scenario

Let's say you need a "Full Width, No Title" template. This is a common requirement for landing pages where you want to use a rich block pattern as a hero section and don't want the default page title to appear.

Goal: Create a template file that omits the header and post title, and allow editors to select it for specific pages.

2. Step 1: Register the Template in `theme.json`

First, you must tell WordPress about your custom template. Add a customTemplates array to the root of your theme.json file.

{
    "version": 3,
    "customTemplates": [
        {
            "name": "template-full-width-no-title",
            "title": "Full Width (No Title)",
            "postTypes": [ "page" ]
        }
    ],
    "settings": {
        "...": "..."
    }
}

Breakdown of Properties:

name: A unique, machine-readable slug for your template. This slug must match the name of the HTML file you will create.
title: The human-readable name that will appear in the editor's template dropdown menu.
postTypes: An array of post type slugs where this template should be available. In this case, it will only be an option for "Pages".

3. Step 2: Create the Corresponding HTML File

WordPress now knows about a template named template-full-width-no-title. It will look for a corresponding file in your theme's templates/ directory.

Create this file: my-theme/templates/template-full-width-no-title.html

The content of this file is just block markup. Notice we are intentionally leaving out the header template part and the post-title block.

<!--
 * File: templates/template-full-width-no-title.html
-->

<!-- wp:post-content {"layout":{"type":"constrained"}} /-->

<!-- We could optionally include the footer -->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

The  block is the magic part—it tells WordPress "render the content that the user builds in the block editor right here."

4. Step 3: The User Experience

Now, when a user edits a Page:

They open the Settings sidebar (the gear icon).
They navigate to the Template panel.
They can click the dropdown and switch from "Default template" to "Full Width (No Title)".

The page will now render using your custom HTML file, giving them the blank canvas they need.

Created: March 20, 2026 • Last Modified: March 19, 2026

Docs Login

Explainer: The customTemplates Property in theme.json