WordPress Theme Post Template Hierarchy Explained

By Joey

Filed under WordPress Theme Development

WordPress utilizes a template hierarchy for themes. What does that mean?

Think of it as a series of “if, else” statements.

When a page, post, or attachment url is called, WordPress looks for matching templates – from specific (ex: a template for a specific category) to generic (the index.php template)

Post Template Hierarchy

  1. if mycustomtemplate.php (selected from Post Attributes)
  2. else single-post.php
  3. else single.php
  4. else singular.php
  5. else index.php

Criteria #1: 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:

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

Additional WordPress Post Template Hierarchy Resources

Want to learn how to build fast, responsive WordPress Themes with modern tools?

Check out my course on Modern WordPress Theme Development.

  • Timber and Twig for clean HTML templates
  • Tailwind CSS for consistent styling
  • Git and Github for versioning your theme
  • Gulp for creating a ready-to-upload theme
  • How to integrate Advanced Custom Fields into your theme