WordPress Tutorial

Understanding the WordPress Template Hierarchy: A Complete Guide

WordPress template hierarchy

If you want to unlock WordPress’ full potential, it helps to know a little about templates. When WordPress renders a page, it uses templates to determine how everything should look. What’s more, the platform adheres to a strict hierarchy that keeps things organized. Knowing what the WordPress template hierarchy is and how it works will enable you to customize your website’s theme more fully.

The WordPress template hierarchy is organized into seven main categories:

  1. Site front page
  2. Single posts
  3. Single pages
  4. Category and tag pages
  5. Custom post types
  6. Search results pages
  7. 404 error pages

In this guide, we’re going to introduce you to WordPress templates and their hierarchy. We’ll also explain how themes use template files to display your website’s pages. We’ve got a lot of ground to cover, so let’s dig in!

An Introduction to Template Files (And How They Relate to WordPress Themes)

When you create a basic static website, you’ll typically just use HTML and CSS to render it and customize its appearance. WordPress, on the other hand, is much more powerful. The platform is built on the PHP language, and it uses several .php files to determine how each aspect of your pages appears.

Take a look at the right side of this post, for example. There’s a sidebar pointing you towards other related posts from our blog. When your browser told WordPress to load this post, it pulled up several ‘template’ files as well, one of which is called sidebar.php. That file includes information on how to render the sidebar you’re seeing right now, and what elements it should include:

An example of a WordPress sidebar.

Sidebars are, of course, only one part of what makes up a full page. Most WordPress pages require several template files in order to work, including the following:

  • index.php
  • header.php
  • sidebar.php
  • footer.php
  • functions.php
  • single.php
  • comments.php

Keep in mind that these are only some of the template files you’ll find in WordPress. header.phpsidebar.php, and footer.php are particularly important, since they’re what’s known as ‘template partials’. This means they can be embedded into multiple other templates.

WordPress’ approach to rendering pages might seem complex at first. However, it’s actually rather efficient. If you had a unique template for every single page on your website, customization would be a nightmare. WordPress’ modular approach to templates enables you to make changes to a single file, and use that element throughout your entire website wherever you need it.

When it comes to choosing which templates to use for each page, the first thing WordPress will do is check out what theme you’re using. Each theme includes its own set of template files that will take precedence over all others. That’s part of what we call the WordPress ‘template hierarchy’ in action, which is something we’re going to explore in the next section.

Now that you understand how WordPress renders your pages, you might start to grasp that themes are basically a collection of template files. In practice, a theme only needs one template file to work, and that is index.php. However, most themes include a lot more templates. For anything a theme doesn’t include, WordPress falls back on the other files in its hierarchy to fill in those gaps.

How the WordPress Template Hierarchy Works

In the last section, we introduced you to some examples of WordPress template files. However, those were just a few of the templates that might be used when a page or post is loaded. The WordPress template hierarchy is what determines which templates are used, and in what order.

If you try to load the page for a hypothetical hosting category, for example, here’s what goes on in the background:

  1. WordPress will look for a template file called category-hosting.php within your current theme’s directory.
  2. If there’s no category-hosting.php file, WordPress will look for one that uses the category’s ID instead, such as category-2.php.
  3. Should WordPress not find either of those options, it will look for a generic category.php file instead.
  4. If if doesn’t find a file called category.php, WordPress will dial it back and look for the archive.php template.
  5. Finally, if all else fails, the platform will load your theme’s index.php file and use it as the page’s template.

Certain template files always take precedence over others, which is why they’re organized into a hierarchy. In broad terms, WordPress websites are made up of seven categories of pages, each with their own strictly-defined hierarchy. Next, let’s explore what those categories are and how their hierarchies work.

Breaking Down the WordPress Template Hierarchy (7 Categories)

As far as WordPress is concerned, all websites can be broken down into seven types of pages. Each of these categories has a built-in WordPress template hierarchy, which we’ll walk you through one by one.

1. Site Front Page

First off, let’s talk about your website’s front page. When WordPress loads your home page, the first thing it will look for is a front-page.php file. If that file isn’t available, the platform will fall back to home.php. Should both files be missing in action, WordPress will turn to the trusty index.php file, which is always there (otherwise, your theme wouldn’t work).

In other words, here’s how this particular hierarchy breaks down:

  1. front-page.php
  2. home.php
  3. index.php

Even if these three files are exactly the same, WordPress will still follow its internal logic. This particular hierarchy is rather simple, of course. Next, let’s dig into a type of page that’s a bit more complex.

2. Single Posts

WordPress articles (such as this one) fall under the single posts category. Near the beginning of this section, we talked about some of the template files involved in rendering a post. However, those were mostly internal elements. Before WordPress can render those, it needs to determine which template file to use for the page as a whole.

Here’s how the hierarchy of single posts works:

  1. single-{post-type}-{slug}.php
  2. single-{post-type}.php
  3. single.php
  4. singular.php
  5. index.php

You probably don’t recognize a few of those template files, so let’s give them some context. First on the list is single-{post-type}-{slug}.php. A more practical example might be single-product-ca-12.php, in the case of an online store. To put it another way, WordPress will look for a unique template file for each post you load, within its specific category. If the platform can’t find a relevant template, it will pedal back to single-{post-type}.php and so on, until it inevitably reaches index.php again.

In practice, this approach enables you to design custom templates for individual posts or products. If you’d rather use a single template for all your posts, however, that’s what single.php is for.

3.  Single Pages

Single pages fall into their own category with WordPress. For example, take the Hostinger website as a whole. https://www.hostinger.com is our homepage, and when accessed it loads the front-page.php template. Other sections of the website, such as https://www.hostinger.com/web-hosting, fall under the category of single pages.

A single page follows this hierarchy:

  1. Custom template file
  2. page{slug}.php
  3. page-{id}.php
  4. page.php
  5. singular.php
  6. index.php

You’ll notice that the first entry on the list isn’t a filename. That’s because WordPress can recognize several types of content as single pages. For example, if you’re dealing with a post, WordPress will default to the hierarchy we discussed earlier. Single pages, on the other hand (such as /web-hosting) will move right on to page-slug.php. In our example, this would be page-web-hosting.php (if such a file exists).

From then on, this hierarchy works the same as with posts. If there’s no template file for a page’s unique slug, WordPress will look for one that matches its ID, and so on. As always, all lines lead to index.php in the end, if you don’t get off at an earlier station.

4. Category and Tag Pages

As you may recall, we actually covered the category hierarchy earlier in this article an as example. In any case, let’s recap the templates this hierarchy covers, in order:

  1. category{slug}.php
  2. category-{id}.php
  3. category.php
  4. archive.php
  5. index.php

This hierarchy works just the same as for single posts and pages. WordPress will look for a template that’s unique to the category you want to load, first by looking for a filename that includes its slug, and then by moving on to its ID. If that approach fails, it will go with category.php instead, and then archive.php. Your WordPress archive should include posts from all your categories, after all, so it makes sense to include it within this particular hierarchy.

We’ve also bundled WordPress tags into this section, because they’re both taxonomic elements. Plus, their hierarchies are exactly alike, except that you would replace all instances of category with tagcategory-{slug}.php becomes tag-{slug}.php, and so on.

5. Custom Post Types

In case you’re not familiar with custom post types, they’re basically types of content that don’t fall within WordPress’ default classifications. For example, if you run a blog that focuses on reviews, you might want to create a custom post type called reviews and customize it to include additional features.

Creating custom post types, however, is a topic for another time. For now, suffice it to say that these types of content have their own hierarchy:

  1. archive-{post_type}.php
  2. archive.php
  3. index.php

As you can see, this hierarchy isn’t as fleshed out as some of the others. However, you still have a couple levels of templates before you get to index.php, which is enough to create complex pages.

6. Search Results Pages

Things get a bit simpler now, with these two last types of WordPress pages. First we have search results, which in most cases are exceedingly simple as far as their layout is concerned. That simplicity is reflected in their hierarchy:

  1. search.php
  2. index.php

In this case, WordPress just defaults to index.php right away if it can’t find a custom template for your search results page. Most modern themes will include some kind of customization for your search page, however.

7. 404 Error Pages

Error pages are one thing you hope your users will never need to see, but they’re important to have around just in case. Out of the box, WordPress doesn’t include custom error pages, but it’s easy enough to set one up.

If you create your own error page, WordPress will look for it first, as demonstrated by this hierarchy:

  1. 404.php
  2. index.php

In our opinion, it can be worth your time to set up a custom error page if you’re getting decent levels of traffic. That way, you won’t scare visitors away on the rare occasion that an error pops up on your website.

The WordPress Template Hierarchy in Action

For this last section, we’re going to take a look at how the WordPress template hierarchy might work in a real-world situation. We’ll use a hypothetical website as an example.

Imagine that you’ve created a website that includes a home page, a couple of single pages, and plenty of posts. You’re also using a custom theme that includes these template files:

  • index.php
  • home.php
  • page.php
  • archive.php
  • category.php

This is a small and tidy collection of template files, but is more than enough to power a website. In this case, if you were to visit the home page, WordPress would load the home.php template.

Here are some examples of other pages you might visit, and the template files they would use:

  • A random post would load index.php as its template file, because there aren’t any other options from its hierarchy.
  • Any category you want to visit would use category.php, since it’s available. If it weren’t, WordPress would load archive.php instead.
  • Your single pages would use page.php, but they would default to index.php if the former weren’t available.
  • Since you don’t have an error page, WordPress would use index.php as a template in that situation.

There are a lot more examples we could use, but these should give you an idea of how this site would work. What templates WordPress will use is determined by which files your theme has set up, and the hierarchies we introduced you to earlier. Hopefully, the information we’ve included here can serve as a reference if you ever need to work with the WordPress template hierarchy in the future.

Conclusion

The WordPress template hierarchy appears complex on the surface. However, in the above sections we’ve laid out which template files take precedence over one another. With this information handy, you’ll know exactly what files you need to alter if you want to make changes to your active WordPress theme.

Do you have any questions about how the WordPress template hierarchy works on your website? Ask away in the comments section below!

About the author

Will Morris

Will Morris is a staff writer at WordCandy. When he's not writing about WordPress, he likes to gig his stand-up comedy routine on the local circuit.

Add Comment

Click here to post a comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Have a website?

Join thousands of webmasters who get our free newsletter with tips on how to drive more traffic and revenue to their websites!

Please wait...

Thank you for sign up!

More in WordPress Tutorial
How to use Facebook debugger
How to Use the Facebook Debugger to Fix Your WordPress Images and Links

Close