The Template Hierarchy in WordPress

Fred Meyer
Fred Meyer / Updated: September 19, 2022
Posted In: Back-End Development
Difficulty:

This article introduces one of the most important topics in WordPress development: the WordPress template hierarchy. It’s one of the most important concepts in all of WordPress theme development. (We have a full free course on the topic, check it out.)

This content is amazing, because it’s not just one of our normal articles: It’s a sample chapter from our “learn WordPress development” guide Up and Running, now in its revised and expanded edition.

If you like this chapter, check out Up and Running. There’s about 40 more chapters where this one came from. It’s the best guide to WordPress development out there.

The Ultimate Way to Learn WordPress Development Concepts

Get Up and Running Today!

Up and Running is our complete “learn WordPress development” course. Now in its updated and expanded 3rd Edition in 2018, it’s helped hundreds of happy buyers learn WordPress development the fast, smart, and thorough way.

Get Up and Running Now

Key Takeaways:

  • The WordPress template hierarchy determines which PHP template files will be used to construct a given webpage on your site, based on the type of post content requested: for example, whether the webpage displays a Page, a Post, or an archive of many Posts.
  • The template hierarchy follows a defined order set in WordPress itself. Learning this hierarchy will let you pinpoint which of your webpages will use which template.

As we work through this chapter, remember the following analogy: WordPress is a factory that processes raw material, posts, into finished products, webpages.

In this chapter, we’re in the stage of the production process where a bundle of posts has been fetched out of the warehouse (the database), and are all ready to be assembled and made to display beautifully by our assembly line, the WordPress theme.

However, the theme provides a lot of possible lines to send those posts down: our different PHP templates. Putting our posts through index.php will result in a webpage that looks one way; putting it through home.php, archive.php, or page.php will give very different results.

How do we know which assembly line a given bundle will go down? With the WordPress template hierarchy. The template hierarchy is a built-in system in WordPress that specifies which line to send a given bundle of posts down, based on properties of the bundle itself.

This chapter explains how the template hierarchy makes its decisions.

index.php: The Ultimate Fallback

For the factory to work, there must always be at least one assembly line that can take any given bundle of posts. This is why every WordPress theme must have an index.php template file.

index.php is the final fallback. Whether you’re building a webpage around all the Posts you wrote in September, or around a single Page, or around the results of a search for all the posts (of any post type) containing the phrase “snow tires,” or around one or more posts of a totally custom post type, such as Recipe or Movie Review, the rule is the same: If the template hierarchy doesn’t find something else to use, it falls back to index.php.

So WordPress can always build out a webpage using index.php if it doesn’t have a more fitting template file to use. However, it will try to find a better template file if one exists.

The Rest of the Hierarchy

WordPress has created some really powerful choice trees for deciding which template to display. From the Codex:

A visual guide to WordPress theme development

Click to enlarge

We won’t be including this in Resources, because it was created by the lovely Michelle Schulp, not us. You can view the full file on this page: https://codex.wordpress.org/Template_Hierarchy#Visual_Overview.

To see what’s going on, let’s follow an example page from left to right on the diagram.

Tracing a Site’s “About Us” Page Through the Template Hierarchy

Let’s see what happens for an imaginary site’s “About Us” page, written as a Page (that is, a post of type Page) and located at site.com/about.

Bundle Type: “Singular Page”

Starting from the very left of the diagram: what’s our “page type”? This question really means, “What kind of bundle of posts are we dealing with?” The answer is “Singular Page,” because the warehouse has sent us a bundle containing only one single (“singular”) post, rather than lots of posts together.

Static Page

Next up, we have two options: is this a “Single Post Page” or a “Static Page”? Don’t let the language confuse you: what they’re really asking is, “Is this a single post of type Post or of any custom post type, or is it a single post of type Page?” It’s the second one, which they’re calling a “Static Page.”

Page Template: Default Template

Okay, are we using a “Custom Template” or a “Default Template”? We’ll get into custom templates later, in Understanding and Creating WordPress Custom Post Templates. You can read this as, “Did you select something other than ‘Default Template’ in the Page Editor?”

Custom post templates

In this case, let’s say we’re not using a custom template on our “About” page. So the right answer for us is “Default Template.”

Template Used: page.php, with index.php Fallback

The next two nodes—page-$slug.php and page-$id.php—are little-used options that let you create templates for individual pages. We don’t have those, so we’ll skate right through them.

That leaves us with the template that will actually display our About page: page.php. And if our theme doesn’t have page.php, we’ll slide all the way back to our ultimate fallback: index.php.

We’ve just finished our first trip through the WordPress template hierarchy. Based on the number and type of posts we’ve retrieved from the database, we’re able to know exactly which of our PHP templates WordPress will rely on to build out the corresponding webpage.

A Second Example: The Blog Index

Let’s take a second trip through the template hierarchy, this time with the site’s blog index page. This is the page on your website that displays your most recent Posts. But which page is this, specifically? It depends on your site’s settings in Settings > Reading:

If you leave the setting as its default, then your blog index is your site’s homepage: the webpage you see when you navigate to yourdomain.com.

However, you can also set your blog index to appear at the URL of an existing “static page” (meaning a Page). Choosing a “static page” for your blog index page will change the blog index’s URL to something like yourdomain.com/blog, for a Page titled “Blog,” or yourdomain.com/news, for a Page titled “News.”

Whatever webpage your blog index is, WordPress knows when you’re visiting it, and it’ll fetch a bundle of your most recent Posts.

Bundle Type: “Blog Posts Index Page”

When this bundle hits the template hierarchy—starting from the left of the diagram—the hierarchy recognizes your “Page Type” as “Blog Posts Index Page.”

Template Used: home.php, with index.php Fallback

As you can see, this tree is simple: your blog index page will display the contents of home.php. If that doesn’t exist, it’ll default back to good old index.php.

Seeing the Whole Hierarchy

Are you starting to get how the template hierarchy works? Once you understand the basic concept, making WordPress themes that benefit from this knowledge simply requires creating and modifying the proper template files for the types of webpages you wish to affect.

The diagram above is great, but there are a few other great ways to visualize and understand the template hierarchy:

  • Template Hierarchy on the WordPress Codex, at: http://codex.wordpress.org/Template_Hierarchy. The Codex is the canonical source for information on the template hierarchy, and on WordPress itself. Learn to love it! On this page, you can learn what each type of template file does.
  • Interactive Template Hierarchy Resource, at: http://wphierarchy.com/. This is an interactive version of the Codex’s template hierarchy image. Click on any node to get help understanding what it means and when it applies.
  • WPTuts+ Cheat Sheet, at: http://wp.tutsplus.com/articles/wordpress-cheat-sheets-template-heirarchy-map/. Especially if you understand WordPress conditional functions like is_home(), we really appreciate the brevity of this visual map. It’s not exhaustive, but it’s easy to read.

Now You Understand the Template Hierarchy

The WordPress template hierarchy is a major part of the magic of WordPress themes and WordPress theme development. Now that you understand its basic workings, you can really dive in and understand exactly which templates apply in which cases.

Get Rid of the Guesswork with Which Template

One final recommendation: If you ever get stuck knowing which template is operating on a particular webpage, you can install a plugin: Which Template. It’s located at https://wordpress.org/plugins/which-template/. When you browse the site while logged-in, it prints the current template into your admin bar, as follows:

The The template currently in use – very useful for WordPress theme development

Which Template indicates that this webpage is using the active theme’s (top right of picture).

This plugin can be a great way to learn the template hierarchy in depth, as you see exactly which template is active at each part of your site.

Next up, something truly awesome in WordPress theme development: The Loop!

Summary Limerick

Do you want to know how WordPress chooses
Which PHP template it uses?
Then let’s learn the parts
of the hierarchy charts,
And the choices it makes won’t confuse us!

Quiz Time!

  1. The WordPress template hierarchy:
    1. Is a customizable set of rules a developer writes for his or her PHP templates
    2. Allows developers to create new kinds of PHP templates
    3. Dictates which PHP template will be used to construct a given webpage
  2. In processing a category archive page—which displays multiple posts that belong to one category—WordPress will first attempt to use which of the following:
    1. archive.php
    2. category.php
    3. index.php
  3. If a particular template file in the hierarchy doesn’t exist, WordPress will:
    1. Move to the next file in the relevant decision tree, ultimately falling back to index.php for all trees
    2. Create and use a standardized version of the missing template file
    3. Display an error indicating that the desired template file could not be found

Answers and Explanations

  1. C. The template hierarchy is how WordPress decides which of the active theme’s PHP template files it will use to construct a specific page.
  2. B. Of the options, it will first try category.php, then archive.php, then index.php.
  3. A. index.php is the template hierarchy’s ultimate fallback, for all types of pages.

Image credit: Edgar Maselskis