A Detailed Guide to WordPress Template Hierarchy

kevin 42 views

This article aims at assisting users to make the most of WordPress with a guide to its template hierarchy. WordPress template hierarchy is among the most important concepts of WordPress theme development because when a page is created, it is the templates that determine how everything should look. As well, WordPress adheres to a strict hierarchy that keeps things in order. Getting insight of the nature and mechanism of WordPress template hierarchy will enable you to efficiently customize your website’s theme.

Key notes:

Ø The WordPress template hierarchy determines which PHP template files will be used to create a specific webpage on your site, based on the type of post content (page, post, etc.)

Ø The template hierarchy follows a defined order set in WordPress itself. As long as you understand this hierarchy, you will be able to identify which template is the most appropriate to your webpage.

Ø 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

Firstly, let’s walk through a brief introduction to the WordPress templates and their hierarchy.

A Quick Introduction to WordPress Template Files

Unlike other basic static websites using HTML and CSS to render and tailor their appearance, WordPress is a much more powerful platform built on the PHP language. This platform uses several .php files to determine how each feature of your sites looks like. WordPress has its own approach to its templates which is rather efficient, especially for customization.

WordPress template hierarchy is basically a list of different templates that are placed in order, each of which is used to display a specific type of content. In practice, one template file called index.php is enough to display the site content. However, most themes have their own set of template files that prevail over others.

In order to select an appropriate template for each page, WordPress usually checks out the theme you are using at first. If your theme is lack of any needed template, other files in its hierarchy will become fallbacks.

As you have gained a general understanding of WordPress template hierarchy, now let’s delve into how it works.

How the WordPress Template Hierarchy Works

As mentioned earlier, it is the template hierarchy to determine the set of templates to be used in a specific order.
For example, if you try to load the page for a hypothetical news category, here’s what WordPress will look for in order.

1. A template file called category-news.php within your current theme’s directory.
2. A template that uses the category’s ID, such as category-2.php if there’s no category-news.php file.
3. A generic category.php file instead in case either of those options is not found.
4. The archive.php template if doesn’t find a file called category.php, WordPress.
5. Finally, if none of the above file is found, your theme’s index.php file will be showed and used as the page’s template.

Certain files are always prior to others, which turns out to be a template hierarchy. In broad terms, a WordPress website is made up of seven pages categories, each with their own strictly-defined hierarchy. Next, let’s explore what those categories are and how their hierarchies work.

WordPress Template Hierarchy in Detail (7 Categories)

In WordPress world, all websites can be classified into seven types of pages. Each of these categories has a built-in WordPress template hierarchy as presented below.

1. Site Front Page

The first thing WordPress looks for when it loads your homepage is a front-page.php file. WordPress will fall back to home.php if that file is not found. If both files are missing in action, WordPress will turn to the index.php file.
In other words, here’s how this particular hierarchy breaks down:

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

It is noted that if these three files are identical, WordPress will still follow its internal logic.

2. Single Posts

WordPress articles are placed under the single posts category. Before rendering different template files to display a single post, first WordPress 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

WordPress will look for a unique template file for each post you load, within its specific category. If a relevant template is not available, it will come back to single-{post-type}.php and so on. Finally, undoubtedly WordPress will reach index.php again.

3. Single Pages

WordPress will look for a template file to render a static page (page post-type). The order in which templates are examined is as below.

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

At the first place is custom template file. Custom template files indicate specific page templates that can be assigned to a particular page or a group of pages. WordPress will look for these template files first and, if found, use the files to render single pages. If there is no custom template files assigned or found, WordPress will continue its search until its final fallback is index.php.

4. Category and Tag Pages

Rendering category and tag archive index pages follows this template hierarchy.

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

Similar to single posts and single pages, WordPress seeks for templates in order until it finds an appropriate template file to render a category/ tag page. WordPress starts searching for a filename that includes category/ tag slug, and then moves to its ID. If both files are not found, WordPress will go for category.php and then archive.php instead. Your WordPress archive should include posts from all your categories, after all, so it makes sense to include it within this particular hierarchy.

The hierarchy to render a category and tag page are quite the same. You just need to replace all instances of category with tag. category-{slug}.php becomes tag-{slug}.php, and so on.

5. Custom Post Types

Ever heard custom post types? Roughly speaking it refers to such contents that don’t fall within WordPress’s default classifications. For instance, you might want to create a custom post type called reviews to display reviews on your site with some additional features.

Creating custom post types, however, is another story to tell. Just for now, we look at the hierarchy of this type of content:

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

You may notice that the hierarchy isn’t as fleshed out as some of the others. Nonetheless, you go through a couple levels of templates before reaching index.php. It is much or less a pathway clear-cut enough to accomplish well-tailored pages.

6. Search Results Pages

For this type of WordPress pages, things get a bit easier now. First let’s take a look at search results, which in most cases are exceptionally simple as far as their layout is concerned. Such simplicity presents in their hierarchy:

(1) search.php
(2) index.php

For this instance, WordPress just defaults to index.php immediately when it can’t put on show a custom template for your search results page. Most modern themes will enable some customizations for your search page, anyway.

7. 404 Error Pages

Error pages should be the only thing you do not want your visitors to see, they are, still, critical in certain cases. At the moment, WordPress custom error pages may not be available on all themes, but it’s simple 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

If your traffic is climbing, it is well worth you setting up a custom error page to keep your site cool out from bothering visitors on some rare occasions when an error pops up.


WordPress template hierarchy may puzzle users at first but it is a powerful tool to keep things clear and logical. Once understanding and using it for building themes, you will take one step closer to the mastery of website development.

Leave a Reply


Get Notified of New Articles

30,000+ people are already subscribed to MakiPlace blog. Leave your email to get our weekly newsletter.