---
tags:
  - wordpress
  - fse
  - theme.json
  - templates
  - custom-templates
title: 'Explainer: The customTemplates Property in theme.json'
---

# 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.

```json
{
    "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.

```html
<!--
 * 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 `<!-- wp:post-content /-->` 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:
1.  They open the **Settings** sidebar (the gear icon).
2.  They navigate to the **Template** panel.
3.  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.