If you want to customize themes or create new ones from scratch, it’s important to understand how the WordPress template hierarchy works.
Try a free demo
First of all, this WordPress system helps keep everything organized. Once you know what all the theme template files are, what they do, and how they’re prioritized, you’ll be able to modify almost every aspect of your WordPress website’s appearance.
In this article, we will explain what the WordPress template hierarchy is and how it works. We’ll then provide a full breakdown of the template files involved in each type of WordPress page (including a cheat sheet for reference), to help you use them to your advantage.
Let’s do it!
Introduction to the WordPress Template Hierarchy
Normally, non-dynamic websites use static HTML and CSS files to render their content. However, WordPress is a dynamic platform based on the PHP programming language. Each WordPress site uploads multiple .php files, each of which governs the look and feel of a specific section or component.
Whenever you load a certain type of page, the Content Management System (CMS) looks for the corresponding template files.
For example, if you use the WordPress search function and load a search results page, the CMS will search for two template files:
- search.php, which governs the look of search results pages
- index.php, which is the default template file WordPress uses when it can’t find the top option inside of each hierarchy
The template files you have access to will depend on the theme you are using. All WordPress themes are a collection of templates, style sheets, and other elements, such as images. So in the example above, if the theme you’re using includes a search.php template, WordPress will find it and load it.
In some cases, you can use a theme that doesn’t include template files for the types of pages you want to upload. That’s where the WordPress template hierarchy comes in. It’s a built-in system that tells WordPress which template files to load and in what order.
For a search page, if WordPress cannot find the search.php file, it will move to the next file in the hierarchy, which is index.php. This file is the final backup for each branch within the template hierarchy.
In theory, you can have a fully functional theme that only includes one template file, and that is index.php.
However, in practice, a theme with a single template file would hardly include style customizations, and each type of page would look pretty much the same. Unless that’s what you’re looking for, understanding the WordPress template hierarchy is one of the most important steps you can take as a theme developer.
How the WordPress template hierarchy works
As you may already know, WordPress allows you to use multiple types of pages depending on what you want to publish. There are seven main categories you can use:
- Front Page
- Individual Posts
- Single Pages
- Custom Post Types
- Search Results Pages
- Category and tag pages
- 404 error pages
Each of those pages has its own custom hierarchy, which means it uses a specific set of template files.
If you take a quick look at any of your theme’s folders, you’ll usually find a collection of template files. The following is an example of template files included in the theme directory for a blog post:
This is a single post page type, which means it uses the single.php file as a template for the main content of the page (the blog post itself).
Also, you have a separate template file for each page element, most of which you should be able to identify at a glance, including:
- Header
- Footer
- Comments
- Sidebar
It is important to understand that although each type of page has its own hierarchy, they also often share common template files, such as header.php and footer.php.
If you’re building your own theme, that means you can create custom styles for each page type, while also creating template files to reuse.
You can also create custom template files for elements like sidebars and footers that only apply to certain types of pages. That flexibility is all thanks to WordPress’ modular approach to templates.
When you switch themes, the differences in layouts you see are attributed to the new template files that WordPress loads. Child themes are also part of the WordPress theme hierarchy, which we’ll discuss shortly.
Where to locate and change WordPress template files
A .php file can include both PHP code and HTML markup (all of which you can edit). As such, WordPress template files can be as complex as you need them to be. In many cases, the template files used by WordPress are a collection of functions for the elements they govern.
To give you an example, here’s a quick look at the header.php template file used by the official Twenty Twenty-One WordPress theme:
As we mentioned, each WordPress theme includes its own set of template files. You can see which template files your theme includes by accessing their folder within the root directory of your website via a File Transfer Protocol (FTP) client.
This is what that looks like for the previous official WordPress theme, Twenty Twenty:
By default, WordPress will load template files that are located within your theme’s main directory (wp_content> themes) or within the template-parts folder.
If you plan to create multiple template files, we recommend keeping your main page templates within the main directory. For more specific template files, like a full width page or sidebar layouts, you can use subdirectories.
The best way to understand the complete hierarchy of WordPress templates is through a cheat sheet. Here’s a visual overview of the template hierarchy, courtesy of the WordPress Codex:
The WordPress Codex includes a lot of information about the template hierarchy, so we recommend bookmarking that resource. For now, let’s dive into each page type and the template files it uses.
A breakdown of the WordPress template hierarchy by page type
WordPress uses seven main types of pages. In this section, we’ll cover each of them and provide a breakdown of the template files they use. Let’s start with the cover.
- Cover Template Files
- Individual Posts
- Individual Pages
- Custom Post Types
- Result Pages search
- Category and tag pages
- 404 error pages
Cover Page Template Files
Your WordPress home page is the first stop most users make when visiting your website. In practice, home page layouts can vary drastically from site to site.
However, for a basic front page, WordPress will look for these three template files in order:
1.front-page.php
2.home.php
3.index.php
If your theme does not include a front-page.php template file, WordPress will default to the second option, and so on. As always, the index.php file is the last stop WordPress makes in the template decision tree.
Single Posts
WordPress single posts use the single post template hierarchy. For the main content of each blog post, WordPress will look for the following files:
- single.php
- singular.php
- index.php
However, if you take a look at the template’s cheat sheet, you’ll notice a more complex hierarchy that arises in some cases.
This is because WordPress allows you to designate template files for individual posts and individual categories, and then defaults to single.php if it can’t find either of those options.
Beyond the primary template files, you have elements like the header, footer, sidebars, and comment sections. As we mentioned before, each of those elements can have its own template file.
Individual Pages
After posts, individual pages are the bread and butter of most WordPress websites. In most cases, they use a different template than your main page, unless both types of pages default to index.php.
This is what the single page template hierarchy looks like:
- page.php
- singular.php
- index.php
Although the template hierarchy for individual posts and pages is similar, there are a few key differences.
First, when it comes to pages, WordPress uses the get_page_templates() route for custom files, which you can use to change or redirect the default page template.
In addition, you can create templates for specific slugs and IDs. If you have a page- {slug} .php file or a page- {id} .php file, WordPress will attempt to load each file in order, before using page.php by default.
Custom Post Types
You can create custom post types for various types of content that you may not want to bundle with Pages or Posts. Custom post types give you a greater degree of organization for your content and also have their own hierarchy of templates:
- archive- {post_type} .php
- archive.php
- index.php
The template hierarchy for custom post types is not that complex as it is for full pages or posts. However, WordPress allows you to create template files for each custom post type, so they don’t have to share the exact same layouts.
Search Results Pages
We’ve already introduced you to the template hierarchy WordPress uses for search results pages, so let’s briefly recap what it looks like:
- search.php
- index.php
As we move away from “complex” page types, such as posts or the home page, the WordPress template hierarchy becomes much easier.
Category and Tag Pages
Although many websites do not link to them directly, WordPress generates collective pages for your tags and categories. There are also specific subpages for each element within that taxonomy.
Considering how complex the taxonomy can be for websites with large content libraries, this hierarchy involves more “steps” than usual:
- category– {slug} .php
- category- {id} .php
- category.php
- archive.php
- index.php
Note that the same hierarchy is used for tags, except that “tag” replaces “category” in all cases.
In theory, you can create individual template files for each category or tag on your WordPress website and identify them via slugs or IDs. However, few websites go through all these problems.
If you don’t plan to allow visitors to browse your category page, feel free to use the archive.php template by default.
404 Error Pages
Sometimes visitors will try to access a page that doesn’t exist. When that happens, WordPress will return a 404 error page.
By default, WordPress does not offer options to customize the appearance of this page. However, you can adjust its appearance yourself through the template file. The template hierarchy is quite short:
- 404.php
- index.php
As your website grows, so will the instances where users may encounter 404 errors. Having a custom error page for those situations can help you let visitors know why the page doesn’t loads, point them in another direction and reduce frustration.
When uploading a 404 template file, WordPress will fetch and upload your custom file before using the default one.
Where do child themes fit in the WordPress template hierarchy
If you like to customize your WordPress themes, one of the best practices is to use a child theme. Child themes also have their place within the WordPress template hierarchy, but it’s not obvious if you look at the cheat sheet we provided above.
In a nutshell, using a child theme adds a second layer to the template hierarchy for whatever type of page you use.
Let’s say you’re using a child theme that includes custom template files for individual pages. This is the order in which WordPress will try to upload files:
- page.php inside child theme
- page.php inside parent theme
- singular.php inside child theme
- singular. php inside the parent theme
- index.php inside the child theme
- . index.php inside the main theme
If WordPress can find a version of a template file within its child theme, that is the one it will load, even if it has a counterpart within the parent theme. In some cases, you may find yourself in a situation where you want to customize the template files for a theme you use, and leveraging a child theme is perfect in those scenarios.
As with other types of customizations, you will lose changes to a theme’s template files when you update it. Adding those changes through a child theme will save you from that situation.
Using WordPress Template Tags for Theme Development
In WordPress development, you will often come across template tags, which are PHP functions that you can use to generate and fetch data dynamically. Template tags are often part of template files, but are not interchangeable.
WordPress creates dozens of template tags in your code, which you can use in theme development. Some examples include:
- get_header()
- get_footer()
- get_sidebar()
- get_search_form()
- get_template_part()<
These tags allow you to collect template files from the theme you are using. In practice, that means you can add specific elements to the parent template files, like front-page.php or index.php.
For a complete list of all the template tags you can use in WordPress development, check out the WordPress Codex.
There, you’ll find instructions on how to use each template tag, its individual parameters, and examples of the code in action.
Summary
Although the WordPress template hierarchy may seem complex at first glance, it boils down to a series of simple decision trees. Whenever you visit a WordPress website, the CMS will see what type of page you are trying to access and then use the hierarchy to determine which template file to load.
Beyond the main templates for each page type, you can also have template files for individual elements like headers, footers, and sidebars.
This modular approach gives you full control over the look and feel of each page on your site and helps save time during the WordPress development process.
Do you have any questions about how the WordPress template hierarchy works? Share them in the comments section below!
If you enjoyed this article, then you are going to love the Phluit WordPress hosting platform. Speed up your website and get 24/7 support from our veteran WordPress team. Our Google Cloud-powered infrastructure focuses on autoscaling, performance, and security. Let us show you the Phluit difference! See our plans
