Understanding the WordPress Template Hierarchy

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. The WordPress template hierarchy is organized into seven main categories:

Site front page, Single posts, Single pages, Category and tag pages, Custom post types, Search results 

pages, 404 error pages.

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 header.php, sidebar.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. 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. 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.

WordPress Template Hierarchy Working

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 'product' category, for example, here’s how WordPress does the job at backend

WordPress will look for a template file called category-product.php within your current theme’s directory.

If there’s no category-product.php file, WordPress will look for one that uses the category’s ID instead, such as category-2.php.

Should WordPress not find either of those options, it will look for a generic category.php file instead.

If if doesn’t find a file called category.php, 

WordPress will dial it back and look for the archive.php template.

Finally, if all else fails, the platform will load your theme’s index.php file and use it as the page’s template. In broad terms, WordPress websites are made up of seven categories of pages, each with their own strictly-defined hierarchy. And 'index.php' template is loaded automatically if nothing is last in hierarchy.

Segregating the WordPress Template Hierarchy

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

Here’s how this particular hierarchy breaks down:

front-page.php

home.php

index.php

Even if these three files are exactly the same, WordPress will still follow its internal logic. 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. Here’s how the hierarchy of single posts works:

single-{post-type}-{slug}.php

single-{post-type}.php

single.php

singular.php

index.php

 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 load single-{post-type}.php and so on, until it inevitably reaches index.php again.

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, A single page follows this hierarchy:

Custom template file

page–{slug}.php

page-{id}.php

page.php

singular.php

index.php

You’ll notice that the first entry on the list isn’t a filename. That’s because WordPress is intelligent and 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:

category–{slug}.php

category-{id}.php

category.php

archive.php

index.php

This hierarchy works just the same as for single posts and pages. 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 tag. category-{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.

These types of content have their own hierarchy:

archive-{post_type}.php

archive.php

index.php

As you can see, this hierarchy has 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:

search.php

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:

404.php

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.