The WordPress template hierarchy is an intricate system that dictates how the WordPress CMS associates a template file with a content type to render your website’s pages. If you’re thinking about creating your own WordPress theme or using a child theme on your website, then you may have to dig into it to get the effects you want on your site.
In this post, we’ll explain everything you need to know about the WordPress template hierarchy, from what it is to how it chooses templates, and we’ll also give you some examples to follow along. By the time you’re done with this post, you’ll have a better understanding of how you can use the template hierarchy in your next project.
Let’s get started!
What Are WordPress Templates?
Before we dive into the WordPress template hierarchy, it’s important to first understand templates. Simply put, templates are files that tell the WordPress CMS how to display different types of pages on your website’s front-end. For instance, since a single post differs from the sidebars in terms of layout and content, each will have their own template files.
Every time a visitor accesses a web page on your site, the WordPress CMS determines which type of page is being requested and then peeks inside its corresponding template file to figure out how to display it. The template file typically contains information about how to structure the web page, what content to display on it, and where to get that content from.
WordPress templates are used in five different main web page types:
- General Templates. These are general templates that the back-end will automatically serve when it can’t find a specific template for the requested content type. It typically includes index.php, search.php, and 404.php.
- Specific Templates. Specific templates allow users to display different content for different listings. These are used mostly in scenarios when you want to display custom fields or add widgetized areas to certain content types only.
- Page Templates. The page templates are used for when you want to have different content on various pages. For instance, if you want some pages to have two sidebars and the rest to only have a single sidebar, then you could configure this using page templates.
- Post Templates. Single post templates and custom post type templates allow users to display different content on different post types. For instance, if you want custom fields to be displayed on custom post types only, then you could configure this using post templates.
- Includes. These are all the extra page elements (such as the WordPress Loop, header.php, footer,php, sidebar.php, etc.) that you can customize through templates.
Now that you have a pretty good idea about what WordPress templates are, let’s take a look at how the CMS manages them on the back-end of your site using the WordPress template hierarchy.
What Do I Need to Know About the WordPress Template Hierarchy?
The WordPress Template Hierarchy (via WP Template Hierarchy)
What do you do when you have a content type that fits into two (or more) templates? A common example is the archive page. Both the archive template and the page template are suitable candidates for this particular web page. Since a template exists for both archives and pages, which template is served to the user on the front-end?
The WordPress template hierarchy dictates the order and priority in which template files are selected. It is essentially a system that organizes different content types.
Additionally, it allows you to customize individualized templates and group together different content types under a new top-level template. And to make sure your site always displays some sort of content, it also has preset templates for when there’s nothing else to display.
So, every time a visitor requests a page, the WordPress CMS traverses down the template hierarchy until it finds a matching template file to serve on the front-end. From the diagram above, it’s easy to see that WordPress prioritizes specific templates over generalized ones. And when it can’t find a match, it will end up at the very bottom of the hierarchy and display the index.php file, which acts as the default template. (This is why the index.php file is required for all WordPress installations!)
How Does WordPress Select a Template?
Let’s step through a few common use case scenarios and see how the WordPress template hierarchy responds to them.
Use Case 1: The Front Page
When you create a WordPress site, one of the first things you have to do is select a front page. By default, WordPress allows you to pick a static front page or display your blog posts dynamically. Here’s how WordPress traverses the template hierarchy in case of a static front page: front-page.php > page-$slug.php > page-$id.php > page.php > singular.php > index.php.
And in case of blog posts on the homepage, it’ll look something like this: front-page.php > home.php > index.php. So for both cases, WordPress treats your website’s home page differently. When you pick a static front page, the homepage serves the template of a single page, whereas when you choose to display blog posts dynamically the homepage serves the home page template.
Use Case 2: Author Archives
You know how most blogs have author archive pages that display the author’s information, biography, links to social media pages, and a collection of all the posts they’ve written? Here’s how the WordPress template hierarchy determines the template to refer to when a visitor requests an author archive page: author-$nicename.php > author-$id.php > author.php > archive.php > Paged: true, paged.php > index.php.
Basically, what happens in the back-end here is that WordPress starts out by trying to find a template file by your name (for example, author-rafay.php), and if it finds it, it will use that template to determine what to display on the front-end. However, if the template doesn’t exist, it’ll look for a template file by the author ID (for example, author-3.php). Similarly, it’ll continue down the hierarchy until it finds a match. As it continues down the hierarchy, the template files become more and more generalized, thus increasing the chances of finding a suitable match. And if nothing matches, then WordPress will simple serve the index.php file.
Use Case 3: Blog Posts
Blog posts, by default, are single post pages. Whenever a visitor tries to access a blog post on your website, this is how the WordPress template hierarchy determines which post to serve: single-post.php > single.php > singular.php > index.php.
Same as before, WordPress starts out at single-post.php and works its way down until it finds a match. Since WordPress treats individual blog posts as static pages, there’s a single post template that determines how the content you publish in them will appear on the front-end. Of course, if even that template file doesn’t exist, WordPress will look for single.php (which also shows up in the hierarchy for custom post types and attachment posts) or end up serving index.php.
WordPress Template Hierarchy and Child Themes
The recommended way to modify a parent theme in WordPress is by creating and using a child theme. When you’re using a child theme on your website, the WordPress template hierarchy takes one more factor into account when choosing which template to serve – priority.
What happens is that the template hierarchy now works through the template files for both the child theme and the parent theme and serve the template that has the highest priority i.e. the one that shows up first in the hierarchy. And if the child theme and parent theme have a duplicate file, then the child theme’s file is given a higher priority.
Say, for instance, you have front-page.php in both your child theme and parent theme. If you select a static homepage, then WordPress will choose the child theme’s front-page.php file. On the other hand, most child themes don’t hold templates for error pages. So, when a template for an error page is needed, the WordPress template hierarchy will serve the 404.php file from the parent theme.
Of course, if any template files from the parent theme show up in the template hierarchy before all of the child theme’s template files, then they will be chosen.
Conclusion
Associating different template files for different types of content allows web developers to build independent components. And the WordPress template hierarchy helps keep website customization organized.
We encourage you to explore it on your own by creating new template files and customizing existing ones. When you want to take things to the next level, you can group content types together to make development even easier.
Do you have any questions about the WordPress template hierarchy? Let us know in the comments section below!
Epicurean Theme