Understanding the WordPress Template Hierarchy

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:

  • index.php : This is the main template file. It and the style.css are required for every theme.
  • style.css : This is the main stylesheet. As stated above, it is required for any theme. It also contains the header comment section with information about your theme.
  • home.php : The home page template file is called for the front page by default. If you do not set a static front page, this template is used to show the latest posts.
  • header.php : This template file usually contains your site’s document type, meta information, links to stylesheets and scripts, and other relevant data.
  • single.php : The single post template is used to present a single post on a webpage.
  • page.php : This template is used when visitors request individual pages, and it can apply to a single page, a page section, or a group of pages determined by class.
  • archive.php : The archive template is used to present posts by category, author, or date. Note: this template will be overridden if the following templates are present: category.php, author.php, or date.php.
  • search.php : The search results template is used to display a user’s search results.

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.

Reading Settings

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:

1. home.php
2. index.php

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:

1. front-page.php : Used for both available options within Settings > Reading.
2. home.php : If the front-page.php file is not available and “your latest posts” is chosen in “Your homepage displays”, WordPress will look for the home.php template file.
3. page.php : When a specific “Homepage” is selected in the “Your homepage displays” section, then the page.php file will be next if the front-page.php file has not been found.
4. index.php : When “Your homepage displays” settings are used but the associated files are not found, WordPress uses the index.php template file as the absolute fallback.

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:

1. privacy-policy.php : (From WordPress version 4.9.6 onward) Used for the Privacy Policy page set in the Change your Privacy Policy page section within Settings > Privacy.
2. A custom template file : The page template assigned to the Privacy Policy page using the get_page_templates() function.
3. page-privacy.php
4. page-{id}.php : If, for example, the page ID is 61 WordPress will look to use the page-61.php file.
5. page.php
6. singular.php
7. index.php

Single Post

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

1. single-{post-type}-{slug}.php : (From WordPress version 4.4 onward) First, WordPress looks for a template of the specific post. For example, if the post type is “blog” and the post slug is “news”, WordPress will look for single-blog-news.php.
2. single-{post-type}.php : If the single-{post-type}-{slug}.php file is not found and the post type is “blog”, WordPress will look for the single-blog.php template file.
3. single.php : If neither of the previous two files could be found, WordPress then falls back to single.php.
4. singular.php : After which it falls back to singular.php.
5. index.php : Finally, as we saw earlier, WordPress ultimately falls back to the index.php file if there is no other viable option.

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:

1. A custom template file : The page template assigned to the page using a get_page_templates() function.
2. page-{slug}.php : If there is no custom template file and the page slug is, for example, recent-news, WordPress will search for the page-recent-news.php file.
3. page-{id}.php : If, for example, the page ID is 61, WordPress will look to use the page-61.php template file.
4. page.php
5. singular.php
6. index.php


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

1. category-{slug}.php : If the category’s slug is “news”, WordPress will look for category-news.php.
2. category-{id}.php : If the category-{slug}.php file was not found and the category’s ID is, for example, 61 WordPress will look for the category-61.php template file.
3. category.php
4. archive.php
5. index.php


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

1. tag-{slug}.php : If the tag’s slug is “breaking”, WordPress will look for tag-breaking.php.
2. tag-{id}.php : If the tag-{slug}.php was not found and the tag’s ID is 61, WordPress will look for tag-61.php.
3. tag.php
4. archive.php
5. index.php
Qode Themes: Top Picks
Bridge New Banner

Creative Multi-Purpose WordPress Theme

Stockholm WordPress Theme

A Genuinely Multi-Concept Theme

Startit WordPress Theme

Fresh Startup Business Theme

Custom Taxonomies

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

1. taxonomy-{taxonomy}-{term}.php : If the taxonomy is sometax, and the taxonomy’s term is someterm, WordPress will look for taxonomy-sometax-someterm.php. In the case of post formats, the taxonomy is ‘post_format’ and the terms are ‘post-format-{format}. For example, the link post format would be taxonomy-post_format-post-format-link.php.
2. taxonomy-{taxonomy}.php : If searching for taxonomy-{taxonomy}-{term}.php did not yield any results and the taxonomy is sometax, WordPress will look for the taxonomy-sometax.php file.
3. taxonomy.php
4. archive.php
5. index.php

Custom Post Types

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

1. archive-{post_type}.php : If the post type is “blog”, WordPress will look for the archive-blog.php template file.
2. archive.php
3. index.php

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:

1. author-{nicename}.php : If the author’s nicename is “Clint”, WordPress will look for author-clint.php.
2. author-{id}.php : If the author’s ID is 61, WordPress will look for the author-61.php file.
3. author.php
4. archive.php
5. index.php


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

1. date.php
2. archive.php
3. index.php

Search Result

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

1. search.php
2. index.php

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:

1. 404.php
2. index.php


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

1. {MIMEtype}.php : This can be any MIME type (Multipurpose Internet Mail Extensions; can refer to files such as image.php, video.php, pdf.php). For plain or text types, the path below is used in the following order:
1.1 text-plain.php
1.2 plain.php
1.3 text.php
2. attachment.php
3. single-attachment-{slug}.php : For example, if the attachment slug is “birthday” then WordPress will search for the single-attachment-birthday.php file.
4. single-attachment.php
5. single.php
6. singular.php
7. index.php


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:

1. embed-{post-type}-{post_format}.php : WordPress first searches for the specific post template. For example, if the post type is “post” and the format is “audio”, WordPress will look for embed-post-audio.php.
2. embed-{post-type}.php : If the post type is “post” and WordPress doesn’t locate the specific post template, it will next look for the embed-post.php file.
3. embed.php : If the first two aren’t found, WordPress will then look for the embed.php template file.
4. wp-includes/theme-compat/embed.php : Finally, if it fails to locate any of the previous files, WordPress will call on the wp-includes/theme-compat/embed.php template.

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:

1. page-hello-world-💯.php
2. page-hello-world-%F0%9F%92%AF.php
3. page-61.php
4. page.php
5. singular.php

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.

Handling Non ASCII Characters

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:

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

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:

* 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' );
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' );
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() );

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.

Post your comment