A Guide to the WordPress Template Hierarchy

If you want to customize themes or build new ones from scratch, it’s important to understand how the WordPress template hierarchy works.

First and foremost, 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 alter almost every aspect of how your WordPress website looks.

In this article, we’ll explain what the WordPress template hierarchy is and how it works. Then we’ll 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 get to it!

Prefer to watch the video version?

An Introduction to the WordPress Template Hierarchy

Typically, non-dynamic websites use static HTML and CSS files to render their contents. However, WordPress is a dynamic platform based on the PHP programming language. Every WordPress site loads multiple .php files, each one governing how a specific section or component looks.

Whenever you load a certain type of page, the Content Management System (CMS) looks for the template files that correspond to it.

For example, if you use WordPress’ search feature and load a search results page, the CMS will look for two template files:

1. search.php, which governs how your search results pages look
2. index.php, which is the default template file that WordPress uses when it can’t find the top option within each hierarchy

The template files you have access to will depend on what theme you use. All WordPress themes are a collection of templates, stylesheets, and other elements, such as images. So in the above example, if the theme you use includes a search.php template, WordPress will find and load it.

In some cases, you might use a theme that doesn’t include template files for the types of pages you want to load. That’s where the WordPress template hierarchy comes in. It’s a built-in system that tells WordPress what template files to load and in which order.

For a search page, if WordPress can’t find the search.php file, it will move down to the next file in the hierarchy, which is index.php. This file is the final fallback for every single 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.

In practice, though, a theme with a single template file would barely include any style customizations at all, and every type of page would look pretty much the same. Unless that’s what you’re going 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 know, WordPress lets you use multiple types of pages depending on what you want to publish. There are seven main categories you 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 those pages has its own custom hierarchy, which means it uses a specific set of template files.

If you take a quick peek into any of your theme’s folders, you’ll usually find a collection of template files. The following is an example of template files listed within the theme directory for a blog post:

This is a single post page type, which means it uses the single.php file as the template for the main content on the page (the blog post itself).

In addition, it has 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’s important to understand that, although each page type 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 type of page, while also building template files to re-use.

You can also create custom template files for elements such as sidebars and footers that only apply to certain page types. 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 also play into the WordPress theme hierarchy, which we’ll discuss soon.

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 that WordPress uses are a collection of functions for the elements that they govern.

To give you an example, here’s a quick look at the header.php template file the official WordPress Twenty Twenty-One theme uses:

As we mentioned, every WordPress theme includes its own set of template files. You can see what template files your theme includes by accessing its folder within your website’s root directory via a File Transfer Protocol (FTP) client.

Here’s what that looks like for the previous official WordPress theme, Twenty Twenty:

By default, WordPress will load template files that are either within your theme’s main directory (wp_content > themes) or within the template-parts folder.

If you plan on creating multiple template files, we recommend keeping your primary page templates within the main directory. For more specific template files, such as a full-width page or sidebar layouts, you can use subdirectories.

The best way to grasp the full WordPress template hierarchy is through a cheat sheet. In this case, we’re showing you 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 dig into each page type and the template files that it uses.

A Breakdown of the WordPress Template Hierarchy by Page Type

WordPress uses seven main types of pages. In this section, we’ll talk about each of them, and provide you with a breakdown of the template files that they use. Let’s start with the front page.

Front Page Template Files

Your WordPress home page is the first stop that most users make when they visit your website. In practice, front page layouts can vary dramatically from one site to another.

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 doesn’t include a front-page.php template file, WordPress will default to the second option, and so forth. As always, the index.php file is the last stop that WordPress makes down the template decision tree.

Single Posts

Individual WordPress articles use the single post template hierarchy. For the main content of each blog post, WordPress will look for the following files:

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

If you take a look at the template cheat sheet, however, you’ll notice a more complex hierarchy that emerges in some cases.

That’s because WordPress lets you designate template files for individual posts and single categories, and then defaults to single.php if it can’t find either of those options.

Beyond the primary template files, you have elements such as the header, footer, sidebars, and comments sections. As we mentioned before, each of those elements can have its own template file.

Single Pages

After posts, single pages are the bread and butter for most WordPress websites. In most cases, they use a different template from your front page, unless both types of pages default to index.php.

Here’s how the single page template hierarchy looks:

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

Although the template hierarchy for single posts and pages is similar, there are some key differences.

First, when it comes to pages, WordPress uses the get_page_templates() path for custom files, which you can use to change or redirect the default page template.

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

Custom Post Types

You can create custom post types for various kinds of content that you may not want to bundle with pages or posts. Custom post types provide you with a higher degree of organization for your content and they also have their own template hierarchy:

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

The template hierarchy for custom post types isn’t as complex as it is for full pages or posts. However, WordPress lets you create template files for each custom post type, so they don’t have to share the same exact layouts.

Search Results Pages

We already introduced you to the template hierarchy that WordPress uses for search results pages, so let’s briefly recap what it looks like:

1. search.php
2. index.php

As we move away from ‘complex’ page types such as posts or your front page, the WordPress template hierarchy becomes much more straightforward.

With a search page, you usually don’t need to include too many elements beyond the results themselves. The simpler the structure, the shorter the hierarchy usually is.

Category and Tag Pages

Although a lot of websites don’t link to them directly, WordPress generates collective pages for your tags and categories. There are also specific subpages for each item within that taxonomy.

Considering how complex taxonomy can become for websites with large content libraries, this hierarchy involves more ‘steps’ than usual:

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

Note that the same hierarchy is used for tags, except that “tag” replaces “category” in all instances.

In theory, you can create individual template files for each category or tag on your WordPress website, and identify them either through slugs or IDs. However, few websites actually go through all that trouble.

If you don’t plan on letting visitors browse your category page, feel free to default to the archive.php template.

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 doesn’t offer options for customizing the look of this page. However, you can adjust the appearance of it yourself through the template file. The template hierarchy is rather short:

1. 404.php
2. index.php

As your website grows, so will the instances when users may run into 404 errors. Having a custom error page for those situations can help you inform visitors why the page isn’t loading, point them in another direction, and reduce frustration.

When loading a 404 template file, WordPress will look for and load your custom file before using the default one.

Where Child Themes Fit into the WordPress Template Hierarchy

If you like customizing your WordPress themes, one best practice is to use a child theme. Child themes also have their place within the WordPress template hierarchy, but it’s not evident if you look at the cheat sheet we provided earlier.

In a nutshell, using a child theme adds a second layer to the template hierarchy for any page type that you use.

Let’s say you’re using a child theme that includes custom template files for single pages. Here’s the order in which WordPress will try to 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 WordPress can find a version of a template file within your child theme, that’s the one it will load, even if there’s a counterpart for it within the parent theme. In some cases, you might find yourself in a situation where you want to customize the template files for a theme that you use, and leveraging a child theme is perfect in those scenarios.

As with other types of customizations, you’ll lose changes to a theme’s template files when you update it. Adding those changes via a child theme will save you from that situation.

Using WordPress Template Tags for Theme Development

In WordPress development, you’ll often run into 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 they’re not interchangeable.

WordPress builds dozens of template tags into its 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 enable you to gather template files from the theme you’re using. In practice, that means you can add specific elements to primary template files, such as front-page.php or index.php.

If you want a full list of all the template tags that you can use in WordPress development, check out the WordPress Codex.

There, you’ll find instructions on how to use each template tag, their individual parameters, and examples of the code in action.

Summary

Although the WordPress template hierarchy may look 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’re trying to access, and then use the hierarchy to determine what template file to load.

Beyond the main templates for each page type, you can also have template files for individual elements such as headers, footers, and sidebars.

This modular approach gives you full control over how each page on your site looks and helps you 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!

Matteo Duò Kinsta

Head of Content at Kinsta and Content Marketing Consultant for WordPress plugin developers. Connect with Matteo on Twitter.

• Website
• LinkedIn
• Twitter