A Beginner’s Guide To WordPress Template Hierarchy

To customize WordPress themes or build a new WordPress theme from scratch, it’s essential to understand what WordPress Template Hierarchy is and how it works.

First things first, it helps in keeping the WordPress system organized. If you know all about theme template files, how they work, how these files are prioritized, then you’ll be able to modify and alter every aspect of how your WordPress site looks. 

Today in this WordPress guide, we’ll discuss in detail what WordPress Template Hierarchy is and how it works. Then we’ll head into the further details of template files.

So let’s get started.

Overview of the WordPress Template Hierarchy

Primarily, to render content non-dynamic sites use CSS files and static HTML. However, WordPress is a dynamic CMS platform based on the PHP programming language. WordPress websites load various .php files, each .php file governs how a component or specific page looks.

Whenever a particular page is loaded, the WordPress CMS immediately starts looking out for those template files that correspond to that particular page. 

Let’s take an example, if you’re using search feature of WordPress and load a search results page, the Content Management System will then look for 2 template file:

1. search.php
2. index.php

The access to templates files you get specifically depends upon what WordPress theme you’re using. Every WordPress is a collection of stylesheets, templates, and various other elements including images. 

So if we consider the above example, if the theme you’re using includes a search.php template, then the CMS will search it and load it. 

In some cases, a theme doesn’t have template files for the types of pages the user wants to load. That’s where WordPress Template Hierarchy steps in. 

SitePoint defines WordPress Template Hierarchy as,

“A WordPress theme is a collection of templates (CSS and PHP files) that WordPress uses to display the database content. WordPress will look for files in a theme to use to render the current page in a specific order. This is called a ‘WordPress Template Hierarchy’, that is used to create and extend WordPress themes.”

Let’s suppose, If WordPress is unable to find a search.php file for a search page, it will automatically move down to the next file available in the hierarchy which is known as index.php. 

Theoretically, a fully functional theme includes only one template file – index.php.

How the WordPress Template Hierarchy Works?

As we all know, WordPress allows users to use multiple types of pages depending on what user wants to publish.  Below are the 7 main categories a WordPress users can use:

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

Each of these WordPress pages has their own custom hierarchy, it means each page uses a specific set of template files. 

If you go and peek into any theme’s folder, you’ll find template files collection. Look at the following example of temple files in WordPress listed in the theme directory for blog posts:

Although, we know each page has its own hierarchy but it’s important to understand that these pages often share common template files like header.php and footer.php.

If you’re developing your own WordPress theme, it means you can also build custom styles for every page, while building template files so you can re-use them later on. For elements like footers and sidebars, you can easily create custom template files that will only apply on specific page types. 

Want to create a custom WordPress theme? Contact us for custom WordPress Development Services.

Breakdown of the WordPress Template Hierarchy

Primarily, WordPress uses 7 types of pages. In this part of this guide, we’ll discuss each page type in detail. So let’s begin with the front page.

1. Front Page Template Files

A WordPress homepage is a page where most of the visitors land when they visit a website. Front pages can dramatically vary from site to site. 

However, a basic front page of a site look out for 3 files templates in order:

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

If your WordPress theme doesn’t include a front-page.php template file, then WordPress will automatically move the next template file listed in the hierarchy. index.php is usually the last stop that WordPress selects from the template file tree.

2.  Single Posts

Every article you post on your WordPress site uses a single post template hierarchy. For each blog post main content, WordPress will search for 3 files including:

1. single.php
2. singular.php
3. index.php

However, users often find template cheat sheet hierarchy more complex sometimes. That’s because WP allows users to designate the template files for single categories and individual posts. If it can’t find any of these options then it defaults to single.php.

Apart from primary template files, there are other elements including header, footer, comment sections, and sidebars. As we mentioned earlier, each of these elements can also have their own template files.

3.  Single Pages

Single pages – the bread and butter for every WordPress site. Usually they use templates different from the front page, unless both the pages default to index.php.

Let’s take a look at single page template hierarchy:

1. page.php
2. singular.php
3. index.php

Even though the hierarchy for single pages and post is similar, yet there are some notable differences. 

Talking about single pages, WordPress uses the get_page_template()path for the custom files. You can use them to redirect or change the default page template. 

Moreover, you can also create templates for specific IDs and slugs. If you have either a page-{id}.php or page–{slug}.php file, then WordPress before defaulting to page.php will load each file in the right order.

4. Custom Post Types

If you don’t want to swarm your site with posts or pages, you can always create custom post types for different sorts of content. Custom post types organize your content in a more efficient manner. Custom post types also have their own template hierarchy:

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

The custom posts template hierarchy is not as complex as it is of full posts and pages. However, WordPress allows you to create template files for each custom post type to avoid confusion in layouts.

5. Search Results Pages

As we have already introduced search results page template hierarchy that WordPress uses so let’s just briefly recap what this hierarchy looks like:

1. search.php
2. index.php

Compared to template hierarchy of front page or single posts, the search page results template hierarchy is much more straightforward.

With a  search page, you don’t have to include too many elements. The hierarchy is usually shorter and simple.

6. Category and Tag Pages

Categories and tags primarily play similar roles when accumulating content within WordPress.  Although not many sites link them to link, WordPress generates collective pages for tags and categories. 

In tags, the template hierarchy works like:

1. tag–{slug}.php;
2. tag-{id}.php;
3. tag;
4. archive.php;
5. index.php.

The hierarchy used for categories is similar to tags, only “category” replaces “tag” in all the instances. 

Theoretically, users can also create individual template files for each tag or category on their WordPress site, and identify them either through IDs or slugs. 

7.  404 Error Pages

You might have tried to access pages while you surf the internet that no longer exist. When this happens, you are redirected to the 404 error page. 

Unfortunately WordPress doesn’t provide options to customize the look of 404 error page by default. If you want to modify or change the appearance of this page you have to do it yourself through the template file. 

The template hierarchy of 404 error pages is short and simple:

1. 404.php
2. index.php

As a WordPress site starts to grow, there are many possibilities that visitors may run into 404 errors. Designing a custom error page can help you to  inform your visitors why the page isn’t loading or redirect them to another page to reduce the frustration. 

When a 404 error occurs, WordPress will first  search and load a custom file before jumping to the default file.

Child WordPress Themes and WordPress Template Hierarchy

If you’re one of those who love customizing their WordPress themes, we believe using child themes is certainly one of the best practices. 

Child WordPress Themes also have a place in the WordPress template hierarchy, however it’s not noticeable when you look at the cheat sheet that we’ve provided you at the beginning of this guide. 

To repiculate, when a child theme is used a second layer is added to the template hierarchy for every page type that you’re using.

Let’s suppose you’re currently using a child WordPress theme that includes custom template files for single pages. Take a look at the in order in which Wp will load files:

1. page.php within the child theme
2. page.php within the parent theme
3. singular.php within the child theme
4. singular.php within the parent theme
5. index.php within the child theme
6. index.php within the parent theme

If there’s a template within a child theme, WordPress will try to find and load it first, even if the counterpart of the template is available within the parent WordPress theme. 

Summary 

To develop custom WordPress themes, it’s essential to have a clear understanding of WordPress Template Hierarchy. It will be beneficial because it will make it easier for you to search right template files to customize and edit. 

Once you get hold of it, you can develop or customize a WordPress theme with your eyes shut. 

We hope this guide will help you in understanding what WordPress Template Hierarchy is and how it works.

Read Also

• How to Fix the WordPress HTTP Error
• How to Fix TERR_SSL_VERSION_OR_CIPHER_MISMATCH Error?
• How to Fix “Your PHP Installation Appears to Be Missing the MySQL Extension Which Is Required by WordPress” Error
• Seven Most Common WordPress Errors
• How to Fix The Error Establishing Database Connection on WordPress
• How to Fix the WordPress Updating Failed and Publishing Failed Errors