Understanding the WordPress Template Hierarchy

For every customizable product, there needs to be a very complex system in place in order to provide a high level of customization. This is also the case with website creation. WordPress has approached this problem with an ultimately elegant solution—theme template files. These files are used to determine what kind of page and which parts would be presented. Since there are large numbers of variations to these files, made even larger by custom WordPress themes, it is integral to have a way to sift through them all to find the appropriate one for the page you are looking at. This is what the Template Hierarchy is for.

In this article we’ll cover the following topics:

Introduction to the Template File System in WordPress

With a static webpage, you only need to use HTML and CSS to create it. The former provides the layout and the latter the style of the page. WordPress, on the other hand, uses PHP to incorporate these and many other resources in order to present a page. This lets WordPress provide its users with the options to customize parts of pages, which is one of the reasons it has gained immense popularity. This customization is possible thanks to different PHP files that are used to determine how each aspect of your page appears. These files are called Template Files.

For example, pages in WordPress are mostly composed of a header, content, sidebar, and a footer. All of these elements are rendered using the header.php, content.php, sidebar.php, and footer.php template files. Although the composition of a page may vary all of those variations need to be defined within their respective template files. This is the case with custom themes, for instance. The files contain information on what a particular part of a page should look like, how it should render, and what parts it should include.

This method of rendering pages used by WordPress might seem complex initially, however, it is quite efficient. The modular approach to templates enables users to make changes to a single file and apply that wherever they like throughout the website.

It is important to note that there are several predetermined template files that WordPress uses, those are:

Along with these there are also many other less common or less necessary template files like: date.php, rtl.css, category.php, tag.php, taxonomy.php, author.php, comments.php, singular.php, front-page.php, page-{slug}.php, single-{post-type}.php, archive-{post-type}.php, attachment.php
image.php, 404.php.

Given all of these files as well as those added by custom themes, WordPress needed to find a way to navigate through them efficiently. The method that WordPress implemented to do that is the Template Hierarchy.

The WordPress Template Hierarchy Explained

In order to have comprehensive customization available for users while remaining fast, efficient, and reliable, WordPress implemented a hierarchy for all those template files. Template Hierarchy is how WordPress searches for the proper template files to use once a page has been requested by a user. Namely, once a user clicks on a link to a certain page, WordPress uses the query string from that link to search for template files it needs to render that page. In order for that search to be as smooth and fast as possible WordPress has predefined the hierarchy of template files. This, in turn, sets the path which will be used to search for the proper template to use.

The following is a representation and explanation of the full Template Hierarchy implemented by WordPress for a number of query types:

Home Page Display

By default, the home page is set to display your latest blog posts. This page is called the Blog Posts Index and can be set by navigating to Settings > Reading.

The home.php template file is used to render the blog posts index, whether used for the front page or any other page of the website. If the home.php file does not exist, WordPress will then use the index.php file to render the page.

So the template hierarchy would go like this:

Note: If the front-page.php template file exists, it will override the home.php template.

Front Page Display

The front-page.php template file, as the name suggests, is used to render your site’s front page. It is used regardless if Your homepage displays option is set to the Blog Posts Index or to a static page. If the front-page.php file does not exist, WordPress will either use the home.php or page.php template files depending on the setup in Settings > Reading. If neither of those files exists, it will use the index.php file. Therefore the template hierarchy would go like this:

Privacy Policy Page Display

The privacy-policy.php template file ( Which was added in the WordPress version 4.9.6 as an editable template) is used to render your site’s Privacy Policy page. It takes precedence over the page.php template file. If the privacy-policy.php file does not exist, WordPress will either use the page.php or singular.php files depending on the available templates. If neither of those files exists, it will use the index.php file. Therefore the template hierarchy would go like this:

Single Post

The single post template file is used to render a single post. For this purpose WordPress uses the following path structure:

Single Page

This is the template file used to render a static page (page post-type). Note that unlike other post-types, the page post-type is specific in WordPress and uses the following path:

Category

In order to render category archive index pages WordPress uses the following path:

Tag

To display a tag archive index page, WordPress uses the following path:

Custom Taxonomies

For custom taxonomies WordPress uses a slightly different template file path:

Custom Post Types

Custom post types use the following path to render the appropriate archive index page.

In order to render a single post type template, WordPress uses the single post display path laid out above.

Author Display

You might have noticed by now that a pattern emerges as you go through these path explanations. And rendering the author display follows that same pattern:

Date

Rendering archive index pages that are date-based (used to display posts by date/time) follows the structure outlined below:

Search Result

The search results template, which serves to display visitors’ search results, follows the structure outlined below:

404 (Not Found)

Likewise, the 404 template file that displays when WordPress isn’t able to locate a post, page, or some other content, is called in the following order:

Attachment

Calling an attachment page (attachment post-type), which displays attachments such as images or other files, follows the path outlined below:

Embeds

To render a post that is embedded in WordPress, the embed template file is called. WordPress version 4.5 and newer use the path outlined below:

Handling Non-ASCII Characters

Using both un-encoded and encoded forms for names was introduced in WordPress version 4.7. If any dynamic part of a template name has non-ASCII characters in its name, users can choose between the un-encoded and encoded form.

For example, the page template hierarchy would look like this for a page with the name “Hello World 💯” and an ID that is 61:

The same structure and behavior will apply to term names, author nicenames, and post slugs as well.

You could test this out and look further into the Template Hierarchy by using either the Show Current Template or Which Template plugins on whichever WordPress theme you’re using. These plugins allow you to see exactly which template files are used on any page of your website. The Show Current Template plugin, for example, allows you to click on the Template option in the admin bar on a page. This, in turn, will open a drop-down containing the full list of the template files being used.

The Template Hierarchy Simplified

In the simplest terms, the Template Hierarchy is a predefined order which WordPress follows in order to find appropriate files with which to build a page. It is essentially a blueprint for WordPress and theme developers to follow so that themes are structured properly and can be interpreted correctly. To illustrate this, we will use a simplified version of one of the examples above.

To display a single post template, which renders a page that shows a single post, there is a chain of five possible files that can be used. Say a user is on a blog list page of a website and sees an interesting article snippet. If they click on its link to read further, multiple things that happen from this point on within WordPress. The process of opening that single post starts with WordPress taking the relevant post information from the query string within the clicked link. Let’s say that the link was for a just-published blog post with a breaking news article. WordPress would take the post type and slug, in this case, “blog” and “breaking”, and would start the search for the template files.

First, it searches for a template file of the specific post that was accessed. This means that it will use the post’s type and slug to search for the single-{post-type}-{slug}.php file. That would be the single-blog-breaking.php template file.

If that file does not exist it will search for the simpler, less specific version, which would be the single-blog.php template file.

Then, if both the first and second file could not be found, WordPress would look for the single.php template file. This is a more common file found in most themes.

However, if for some reason the single.php file is not found, WordPress will then search for the singular.php template file.

Finally, if no other file is available WordPress will default to the index.php template file.

So the full Template Hierarchy for the single post template would look like this:

You may have noticed that each of the hierarchies laid out above ends with the index.php file. This is a measure WordPress has taken in order to ensure that there is always a file it can use to render a page. This is also one of the main reasons why you cannot activate a theme that does not have an index.php file within it.

The WordPress Template Hierarchy in Code

Now that we have seen what the Template Hierarchy is in general, let us delve into the code that forms it. We mentioned in the previous paragraph that one of the main reasons WordPress does not allow activation of a theme is that the index.php file is missing. The other major reason is more technical in nature—most requests to a WordPress website go through the index.php file. It contains the following lines of code:

<?php
/**
* Front to the WordPress application. This file doesn't do anything, but loads
* wp-blog-header.php which does and tells WordPress to load the theme.
*
* @package WordPress
*/
/**
* Tells WordPress to load the WordPress theme and output it.
*
* @var bool
*/
define( 'WP_USE_THEMES', true );
/** Loads the WordPress Environment and Template */
require( dirname( __FILE__ ) . '/wp-blog-header.php' );

The final line of code above is what pulls in the wp-blog-header.php file. This file, in turn, contains the following lines:

if ( !isset($wp_did_header) ) {
$wp_did_header = true;
require_once( dirname(__FILE__) . '/wp-load.php' );
wp();
require_once( ABSPATH . WPINC . '/template-loader.php' );
}

Now, for our purposes, the interesting line here is:

require_once( ABSPATH . WPINC . '/template-loader.php' );

This line loads the template-loader.php file. This is the file that contains the template hierarchy. And that core part that defines the template hierarchy is:

if ( wp_using_themes() ) {
$tag_templates = array(
'Is_embed' => 'get_embed_template',
'is_404' => 'get_404_template',
'is_search' => 'get_search_template',
'Is_front_page' => 'get_front_page_template',
'is_home' => 'get_home_template',
'is_privacy_policy' => 'get_privacy_policy_template',
'is_post_type_archive' => 'get_post_type_archive_template',
'is_tax' => 'get_taxonomy_template',
'is_attachment' => 'get_attachment_template',
'is_single' => 'get_single_template',
'is_page' => 'get_page_template',
'is_singular' => 'get_singular_template',
'is_category' => 'get_category_template',
'is_tag' => 'get_tag_template',
'is_author' => 'get_author_template',
'is_date' => 'get_date_template',
'is_archive' => 'get_archive_template',
);
$template = false;
// Loop through each of the template conditionals, and find the appropriate template file.
foreach ( $tag_templates as $tag => $template_getter ) {
if ( call_user_func( $tag ) ) {
$template = call_user_func( $template_getter );
}
if ( $template ) {
if ( 'is_attachment' === $tag ) {
remove_filter( 'the_content', 'prepend_attachment' );
}
break;
}
}
if ( ! $template ) {
$template = get_index_template();
}
/**
* Filters the path of the current template before including it.
*
* @since 3.0.0
*
* @param string $template The path of the template to include.
*/
$template = apply_filters( 'template_include', $template );
if ( $template ) {
include( $template );
} elseif ( current_user_can( 'switch_themes' ) ) {
$theme = wp_get_theme();
if ( $theme->errors() ) {
wp_die( $theme->errors() );
}
}
return;
}

The first part of the code is a simple array, called $tag_templates, that consists of all possible template files. The second part has somewhat changed throughout the years. It used to be a large but simple if-else statement. However, the latest version consists of a for-loop that iterates through all of the $tag_templates array items. Each iteration checks whether that particular array item has been populated previously or not. This way it exhausts possibilities within the hierarchy so that it can later filter these and find the appropriate file to use.

For such a crucial element of the inner workings of WordPress, this is a rather simple and elegant solution. It doesn’t pose problems to either WordPress or theme developers and most of the time regular users don’t even need to learn of it. All of this means that it has fulfilled its purpose flawlessly.

Final Thoughts

We hope that this tutorial has helped you come to grips with the concept of Template Hierarchy and how it works. Whether you are a beginner or a more knowledgeable WordPress user, we are sure that this information will come in handy for any custom work that you wish to get done. Make sure to keep the article handy as it is a great cheat-sheet to all of the hierarchies proposed by WordPress.