WordPress Theme Post Template Hierarchy Explained

When I first discovered that WordPress utilizes a template hierarchy for themes, I wanted to understand what it meant.

I’m very familiar with MODX, where you explicitly select a template for your page or post (called resources).

WordPress is different. The core chooses which template to use, based on the requested url and template file name criteria. (essentially just a series of “if else” statements)

This “criteria” is called a template hierarchy.

In this article we will stick to examining the template hierarchy for posts only.

Let’s start by looking at standard blog posts (non-custom post types), then we will look at custom post types.

WordPress Template Hierarchy for Standard Blog Posts

Here is the WordPress standard post template hierarchy in order (specific to general), followed by a more detailed explanation:

Standard Post Template Hierarchy

  1. Selected custom template from Post Attributes
  2. single-post.php
  3. single.php
  4. singular.php
  5. index.php

Standard Post Template Hierarchy Explanation

Criteria #1: If you publish a standard blog post in WordPress, the WordPress core will first check to see if you selected a custom template from the dropdown under the “Post Attributes” section.

For example, you could create a unique template called fancypost.php. Just include the following HTML comments at the top of your template file:

<?php
/*
 * Template Name: Fancy Post
 * Template Post Type: post
 */

The custom template will now show up on all standard blog posts under the Post Attributes like so:

Select your custom template from the Post Attributes section of your blog post.

Criteria #2: If you have not selected a custom template, it will use the single-post.php template. As the name suggests, only single posts will use this template.

Criteria #3: If single-post.php doesn’t exist, it will check for the single.php template file.

What’s the difference between single-post.php and single.php? Both attachments and custom posts use single.php within their hierarchy structures as well.

Criteria #4: After that, it will check for singular.php (which is a catch-all for pages, posts and attachments).

Criteria #5: Finally it will default to using index.php.

WordPress Template Hierarchy for Custom Post Types

Here is the WordPress custom post template hierarchy in order (specific to general), followed by a more detailed explanation:

Custom Post Type Template Hierarchy

  1. Selected custom template from Post Attributes
  2. single-$posttype-$slug.php
  3. single-$posttype.php
  4. single.php
  5. singular.php
  6. index.php

Custom Post Type Template Hierarchy Explanation

Criteria #1: If you publish a custom post type in WordPress, the WordPress core will first check to see if you selected a custom template from the dropdown under the “Post Attributes” section.

This is the same as with standard posts. However, you need to make sure to add your custom post type to the HTML comments at the top of the file.

For example, if you registered a custom post type called “fancy”, you would need to add that type to the file comments section:

<?php
/*
 * Template Name: Fancy Post
 * Template Post Type: post, fancy
 */

The custom template is now available for both standard blog posts and custom “fancy” blog posts under the Post Attributes template select dropdown.

Criteria #2: If you have not selected a custom template, it will use the single-$posttype-$slug.php template, where the $posttype is the name of your custom post type, and the $slug is the slug of the post.

The slug is also the unique url extension when permalinks are set to %postname% under Settings->Permalinks. Since this is common practice, a template using a slug in the name will be unique to only a single custom post type.

However, if you are using a different permalink setting, you can reuse the same slug for different custom posts and they will all use the same template.

Criteria #3: If single-$posttype-$slug.php doesn’t exist, it will check for the single-$posttype.php template file.

If we created a single-fancy.php template, post publishers wouldn’t have to worry about selecting a custom template from the Post Attributes template dropdown. WordPress would just automatically match the custom post type to the template.

This is the most common practice for creating custom templates for custom post types.

Criteria #4: After that, the WordPress core will check for single.php.

Criteria #5: Next, the core will try and find singular.php.

Criteria #5: Finally it will default to using index.php.

What theme template naming conventions should you use for standard and custom posts?

If I were creating a custom WordPress theme with custom post types, I would create a single-post.php for all standard blog post entries, and as many single-$posttype.php templates for each custom post type.

This just feels like a good logical way to keep my post templates separate and specific.

Even though the WordPress core will always default to using index.php as a template for any post, I would always create a single-post.php file in my themes so it’s very clear what template is being used for single blog posts.

Additional WordPress Post Template Hierarchy Resources