A Straightforward Guide to the WordPress Template Hierarchy

Get a free WP Checkup Today!
Get a completely free health check of your WordPress site, no email or signup required.

If you’re building your own themes for WordPress, or using a child theme to customize a third party theme, at some point you’ll come across the template hierarchy.

It’s a brilliant system that dictates how WordPress chooses which template file to use for different types of content. It takes into account content types (e.g. posts, pages, attachment and custom post types), taxonomies (e.g. in category, tag and custom taxonomy archives) and even lets you create bespoke templates for specific pages.

But it can be confusing. When faced with an archive for a taxonomy that applies to a post type, for example, which template should you use? And how do templates for single posts work?

In this post I’ll walk you through the template hierarchy and explain how it works with some worked examples. By the time you’ve read through this you should be able to create theme template files like a pro!

The wphierarchy site is a great refresher on the template hierarchy.
The wphierarchy site is a great refresher on the template hierarchy.

Note: my favorite resource on the template hierarchy is wphierarchy, which has a clear interactive diagram.

The WordPress Template Hierarchy: Types of Templates

The template hierarchy dictates how WordPress deals with five main page types:

  • There are three template files that are more general. The fallback template file is index.php. This is used if WordPress can’t find anything else for the specific content type. It should, therefore, work correctly for archive pages, single posts and single pages (as well as all other content types). A theme has to have an index.php file to work; it could, in theory, have just this file and the stylesheet. The other general template files are 404.php for errors and search.php for search results.
  • Templates for specific archive displays, like category and taxonomy archives, let you display different content for different listings. For example you could use alternative archive template files if one post type has custom fields you want to display, if you want to alter the loop or if you want to add extra content or widget areas.
  • Page templates help you display different content on different static pages (for example if you want to display a sidebar on some pages but not all). You can then choose which template a given page uses via the admin screens.
  • Single post templates, including custom post type templates, let you display different content for different post types, for example if you want to use the loop differently (e.g. displaying different metadata).
  • Includes, such as header.php, sidebar.php and footer.php, can be created for different areas for the site in place of or as well as a template file, to display different widgets or content in these areas of the site. They don’t just have to be for headers, footers, and sidebars though – you can use an include anywhere you want to save writing the same piece of code into every template file. A common example is the WordPress Loop.
page attributes meta box in the wordpress page editing screen
On my website I’ve set up a number of page templates which I can select in the page editing screen

How WordPress Chooses a Template File

When WordPress opens a page on your site it checks what content type is being displayed and then chooses the correct template file accordingly.

For static pages:

  • singular.php overrides index.php, and then page.php overrides both.
  • page-$slug.php or page-$ID.php override page.php when a page with the correct slug or ID is being displayed
  • front-page.php beats index.php and page.php when the home page is viewed.
  • A custom template page, such as page-without-sidebar.php, when selected through the page’s admin panel, beats page.php, home.php, page-$slug.php and page-$ID.php.

For individual posts and attachments:

  • singlular.php overrides index.php, and single.php beats both.
  • single-post.php overrides single.php when a single post is being viewed (as against an attachment or a custom post type).
  • single-$posttype.php beats single.php when displaying a single post of a given post type.
  • single-$posttype-$slug.php beats single-$posttype.php for a post with the given slug.
  • attachment.php overrides single.php when an attachment is viewed.
  • A custom MIME type page ($mimetype.php) beats attachment.php when attachments of a given MIME type are viewed. For example, you could use image.php, video.php, or any accepted MIME type.

For archives:

  • home.php beats index.php for the home page or the main blog. If the home page is the main blog page, then front-page.php beats both of these.
  • archive.php beats index.php when a category, tag, date, or author listing is viewed.
  • category.php overrides archive.php when a specific category listing is viewed. A category-$slug.php or category-$ID.php template override category.php when displaying posts from the relevant category ID or slug.
  • tag.php overrides archive.php when a tag listing is viewed. A tag-$slug.php or tag-$ID.php file override tag.php.
  • author.php overrides archive.php when the list of posts by an author is viewed, which in turn is trumped by author-$ID.php and author-$nicename.php.
  • archive-$posttype.php beats archive.php when listings for a given post type are being viewed.
  • date.php overrides archive.php when a list of posts for a given date is viewed.
  • taxonomy.php overrides archive.php when viewing a taxonomy archive. For a specific taxonomy, taxonomy-$taxonomy.php will also beat that (where $taxonomy is the taxonomy slug), and for a term in the taxonomy, taxonomy-$taxonoomy-$term.php will beat all of these.

In addition:

  • search.php trumps index.php when the results from a search are viewed. You might expect a search to use an archive template but it doesn’t: it either uses index.php or search.php if that exists.
  • 404.php beats everything else when a URL is displayed for which WordPress can find no content. You can use this to display some custom content for 404 pages, such as an error message and search box.
  • index.php is essential for the theme to work as WordPress will fall back to it when displaying content not accounted for by any of the other templates you’ve set up.

A Worked Example

Let’s imagine my site has a number of single pages, a front page with static content, plenty of archives, a post type of product and a taxonomy of productcat.

My theme has these template files:

  • index.php
  • front-page.php
  • page.php
  • mypagetemplate.php
  • single.php
  • archive.php
  • category.php
  • taxonomy.php
  • taxonomy-productcat-featured.php
  • 404.php
  • search.php

Which file do you think WordPress would use for these pages in my site?

  • The home page (a static page)
  • A static page
  • A single post
  • A product
  • A product with the featured term in the productcat taxonomy
  • An error page
  • A search page
  • A category archive
  • A tag archive.

See if you can work out from my guide above which template file my site would use for each of those pages. No checking below!!

Here are the answers:

  • The home page: front-page.php
  • A static page: page.php (or mypagetemplate.php if I select that in the page admin screen)
  • A single post: single.php
  • A product: single.php
  • A product with the featured term in the productcat taxonomy: taxonomy-productcat-featured.php
  • An error page: 404.php
  • A search page: search.php
  • A category archive: category.php
  • A tag archive: archive.php

Did you get them all right? If not, take some time to work through each and familiarise yourself with how WordPress would work through the template hierarchy.

Include Files

As well as the template files, WordPress uses a number of includes, which are used for content which will be inserted into a template. The most common includes are header.php, sidebar.php and footer.php, all of which can have multiple versions such as header-home.php, sidebar-$posttype.php or whatever’s needed for your site.

To call the generic header in your template file, use get_header():

If you want to create a specific header include file for one of the content types on your theme (e.g. the home page), you could create a file called header-home.php and then call it like this:

This would call the header-home.php file and output its contents where you place it in the template file (which should be at the top). You would either use this in place of the standard include in the relevant template file (in this case home.php), or you could use it in a conditional function, as below:

You can use this to call one of multiple includes depending on what part of the site the user is in.

As well as the header, sidebar and footer includes, WordPress makes use of some other standard includes:

  • get_search_form() fetches the searchform.php file from your theme – if one doesn’t exist, WordPress will generate the search form
  • comments_template() fetches the comments.php file from your theme – if there isn’t one, it will include wp-includes/theme-compat/comments.php from WordPress core.
  • get_template_part() fetches custom includes such as the loop for example. This helps you make your themes more efficient by only coding once. So if you have one loop.php file and call it in all your template files, then you only have to edit the code once if you want to change your loop.

To use get_template_part() to call the loop.php file, you’d use this:

Template Files and Child Themes

But what if you’re using a child theme to modify a parent theme? You may be wondering how the template hierarchy works in that case.

The good news is that it’s pretty simple: WordPress will work through the template files for both themes and use the one that’s highest in the hierarchy. If both themes have the same file duplicated, then it will use the one from the child theme. This is how you use a child theme to override a template file in a parent theme.

So for example, my parent theme has these files:

  • index.php
  • front-page.php
  • page.php
  • single.php
  • archive.php
  • category.php
  • 404.php
  • search.php

And my child theme has these files:

  • front-page.php
  • mypagetemplate.php
  • single.php
  • category.php
  • taxonomy.php
  • taxonomy-productcat-featured.php

Which file do you think WordPress will use now for each of these pages?

  • The home page (a static page)
  • A static page
  • A single post
  • A product
  • A product with the featured term in the productcat taxonomy
  • An error page
  • A search page
  • A category archive
  • A tag archive.

The answers are below.

  • The home page: front-page.php from the child theme
  • A static page: page.php from the parent theme (or mypagetemplate.php from the child theme if I select that in the page admin screen)
  • A single post: single.php from the child theme
  • A product: single.php from the child theme
  • A product with the featured term in the productcat taxonomy: taxonomy-productcat-featured.php from the child theme
  • An error page: 404.php from the parent theme
  • A search page: search.php from the parent theme
  • A category archive: category.php from the child theme
  • A tag archive: archive.php from the parent theme

Note that if a template file from the parent theme is higher in the hierarchy than all the files in the child theme, then the file from the parent theme will be used. It’s only when the files are duplicated that the child theme’s file trumps the parent theme’s file, or if the child theme’s file is higher in the hierarchy.

Understanding the Template Hierarchy Will Make You a Better Person Theme Developer

Phew! We’ve covered a lot in this post and I’ve asked you to do some thinking. Hopefully you now understand how the template hierarchy works and you can use it to identify which template file WordPress will use to display which page in your site.

The template hierarchy is a great feature of WordPress: it keeps things clear and logical, and if you make reference to it when building your themes, you shouldn’t go wrong.

I hope this guide has gone some way to breaking down for you how the template hierarchy works! If you have any questions, let me know in the comments. VIEW 17 comments
Get a free WP Checkup Today!
Get a completely free health check of your WordPress site, no email or signup required.