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

Ship fast, responsive websites with confidence.

Level-up your front-end skills through weekly emails and project-based courses.