Creating templates for custom post types

Level: ,

Estimated reading time: 4 minutes

Several theme developers have reached out asking how to create full site editing templates for custom post types. In this lesson, I will briefly explain:

  • How to add file-based templates for custom post types to your block theme
  • How to create templates for custom post types in the Site Editor

Prerequisites: For the templates and the Site Editor options to be available, you must first register the custom post type. This Site Editor feature is only for creating templates, not for creating custom post types from scratch.

Last updated

How to add file-based templates for custom post types

The difference between creating a template file for a default post type and a custom post type is the naming of the file. If the name of your custom post type is “book,” you need to name the default single template single-book.html. A template for a specific book would be named single-book-{book-title}.html, and the archive would be called archive-book.html

  • Use an HTML file if you want the Site Editor to list the template.
  • Use a PHP file if you need to:
    • Use conditionals
    • Display post meta in the content
    • Check if a plugin is active before adding a plugin block to the template
    • Support a plugin that is not compatible with the Site Editor

Remember to place HTML templates in the templates folder and PHP templates in the theme’s root folder.

You can read more in the official documentation in the theme developer handbook:

How to create templates for custom post types using the Site Editor

The instructions and screenshots below are for WordPress version 6.2. The feature is partially available in WordPress 6.1, but the interface looks different.

In the WordPress admin area, open the Site Editor by going to Appearance > Editor. In the Navigation Sidebar (the dark grey menu), select “Templates”:

Click on the plus icon to add a new template. This opens up a scrollable modal window with a list of templates that you can create. Note that if a template already exists, it will not show in the list, then you need to edit (or delete) the existing template instead.

The example shows two custom post types: Book and Movie, and a custom taxonomy: Genre. You can create the following templates:

  • A default template for all items of the post type
  • A template used for one single item of the post type
  • The custom post type archive
  • The custom taxonomy archive.

As an example, when you click on the “Single item: Book” option, you will be prompted to choose if you want to create a template for all books, or for a specific book:

The second step of adding a template displays a modal with two buttons. The button text is the post type name followed by the option description: "For all items", and "For a specific item".

If you select the option “For a specific item”, you will see a list of the book items that you have saved on your website, and you will be able to choose one:

When you create a template for a specific item, you are presented with a select list with the item title (post title), and also the link to that item.
You can select one item.

When you choose to create a single item, the editor copies the single post template and re-uses it. For post type and taxonomy archives, the editor creates a copy of the archive template. Secondly, If the single or archive templates do not exist, WordPress falls back to using the next template in the template hierarchy, the index.

In the final step, the Site Editor opens the newly created template so that you can edit, add and remove the blocks.