The WordPress template hierarchy is one of the most influential things in the life of theme developers. Users may need to understand it, plugins may need to interact with it, but generally it is theming that’s all about the template hierarchy.
That’s because it is the WordPress template hierarchy that determines which of the files in a theme is used at a given time. That is: the template hierarchy is the foundation upon which WordPress themers make their art.
The purpose of this article is to further elucidate this idea. We will define what the template hierarchy does, why you need to know about it to be an effective modifier of WordPress sites, and we’ll talk about how to work with it and (very briefly) how it works.
What is the Template Hierarchy?
At its heart, the template hierarchy is the choice-structure WordPress uses to determine what file in the theme will be used to generate the full, final HTML for a given page of your WordPress website.
WordPress needs to have a way to know how to interact with the theme. It would be possible that someone could write various different types of complex PHP logic for their theme that explained to WordPress how to interact with it. It could, perhaps, be a PHP class that matched a WordPress-defined interface (in the object-oriented programming sense) that each theme would need to respond to.
But that’s complicated—to read, let alone to do. And that’s precisely the point of the template hierarchy: for WordPress to successfully be able to use different themes but also make it relatively easy to create and modify themes, a simpler solution was needed. And that’s what the template hierarchy is.
At its heart, the template hierarchy is the choice-structure WordPress uses to determine what file in the theme will be used to generate the full, final HTML for a given page of your WordPress website.
Most files in a WordPress theme are actually members of the template hierarchy, and WordPress will choose to call on one of them depending on what kind of information it’s trying to show.
Walking the Template Hierarchy
If WordPress needs to show the posts (or any content type) by a specific author (user) on a WordPress site, it has a couple needs. Primarily:
- It needs to make it easy for someone making or modifying a theme to customize a page
- It needs to make sure that if no customizations were needed, it’ll have something to use
To accomplish this, the template hierarchy will try different files in the currently-active theme. If they exists, it’ll use them. If they don’t, it’ll keep moving on.
So in looking to find the template to use to present all the posts for given author, let’s make that authors username “david” who has a numeric id of 3. (Surely a coincidence. ;p) WordPress needs to know what file from your current theme to use. So here’s how it looks through your theme files:
- Does the file
author-david.phpexist? No… - Does the file
author-3.phpexist? No… - Does the file
author.phpexist? No… - Does the file
archive.phpexist? No… - Does the file
index.phpexist? Yes!
You’ll notice that there are five “no”s before WordPress gets a yes. Each of them, and the following question are the template hierarchy. As soon as WordPress gets to a “yes” on one of these questions, the template hierarchy’s role is done. But this is really important.
The file that’s found is responsible for the HTML of the whole page. Literally anything that WordPress does or shows on a page of your site comes from a single template hierarchy file in your theme. (As you probably already know, that doesn’t mean that all the stuff WordPress does is jammed into that file, but the ways that that other stuff gets pulled in is outside the scope of this article.)
So it’s these questions (WordPress decided which to look for based on the URL that person is visiting) that make up the template hierarchy. And just so you know, if you don’t have an index.php, you don’t have a WordPress theme. That’s the last stop for every part of the template hierarchy.
The Ultimate Fallback: What and Why
As I just said, without an index.php, you don’t have a WordPress theme. But, if you have one, you don’t really need any other files that you might use from the template hierarchy. That the other thing to realize.
WordPress needs, as we said above, some certainty that it will always be able to make a page for the end user. A theme must provide that. So that’s what the template hierarchy is for. But the need for a final fallback is absolute, and that’s why WordPress doesn’t let you enable a theme that doesn’t have an index.php file.
Why the WordPress Template Hierarchy Exists
The template hierarchy exists to make it easier for theme designers and developers to customize the look of a WordPress site. It’s very common for a client to make the “tag archive” pages for their blog different from the single-post page. So WordPress’s template hierarchy supports that need.
As we mentioned above, there are alternatives to the template hierarchy that one can imagine. But few of them are any good. And that, fundamentally, is the entire reason why the template hierarchy exists.
A Quick Discussion of Child Themes
As you may know, WordPress has these things called child themes. And really, WordPress child themes are more than half of the reason to love the template hierarchy. Child themes are way that designers and developers can make small tweaks to specific pages of a site without having to create a whole theme for themselves.
The full design of child themes is a topic for discussion well beyond this article. To learn more about child themes, you’ll be well served by these two articles on WPShout, or this one on the WordPress.org site.
The core thing to know about child themes is that the WordPress template hierarchy is aware of them and works with them. So what I earlier explained about looking for files above for an author template is actually a little different if a child theme is being used. If it does, it’ll look like:
- Does the file
author-david.phpexist in the child theme? No… - Does the file
author-david.phpexist in the parent theme? No… - Does the file
author-3.phpexist in the child theme? No… - Does the file
author-3.phpexist in the parent theme? No… - Does the file
author.phpexist in the child theme? YES!
You’ll notice that’s more steps to get as far into the template hierarchy. You’ll also notice that the child theme is always checked first. This is a really important thing about the template hierarchy and child themes—their files always beat those of a parent, where the template hierarchy is concerned.
Why You Need to Understand the WordPress Template Hierarchy
Theming without having a good understanding of the template hierarchy is nearly impossible. You can maybe do it, but it’ll feel like confusing and mystifying magic.
It’ll also help, if you’re trying to do that, to know about some plugins that make the template hierarchy a little clearer: Which Template and Show Current Template. These both do the same thing (which is useful if you do know the template hierarchy too): they tell you which template-hierarchy file is being used to build a given page. They both actually tell you a bit more than that, but that’s their primary use (at least for me).
Why you need to know about the template hierarchy and understand its structure—even with Which Template in your toolbelt—is that you’ll use it to “override.” For child theming, an “override” is as easy as creating a file with the same name in your child theme and calling it good. But when you’re trying to be more specific than that, you’ll need to refer to a diagram of template hierarchy. That’s where I always reach for wphierarchy.com. WordPress.org has a diagram, as does a Google Image search. But nothing is quicker to access from an idle state than this site.
How to Work with WordPress’s Template Hierarchy
If you’ve read linearly, I think you already have a pretty good answer to this question. But this is the internet and I know people skim. You work with the template hierarchy by making a theme. Whether it’s a self-supporting theme or a “child” that leans on a “parent”, a theme’s files are fundamentally how you change the way you work with the template hierarchy.
Basically, you create the file that matches where in the template hierarchy you’re trying to change the way the page looks. So if you’re trying to make the HTML for a single page look different, you’ll be able to specify a page template, or make a file in your theme with that post’s ID rolled in.
Neither of these are perfect. But that’s fundamentally how it works.
How the Template Hierarchy Works Inside WordPress Code
“How does the WordPress template hierarchy work?” is really an academic question that almost no WordPress developer ever needs an answer to. But, one day I found myself just casually wondering, and so I looked it up. And this article came out:
The short answer, for those interested in reading this but not interested enough to click, is a bunch of ifs and elseifs in PHP code. Not much more. It’s not the most elegant code that underlies this powerful and important facet of WordPress, but it works well and enables all the themes you’ve ever known and loved in WordPress. Pretty cool!
Further Reading on the Template Hierarchy
If you’re new to some of the concepts in this article, or just need a refresher, please check out these other articles we’ve got. First, two for beginners:
Then, for those looking to dive deeper and think harder about the template hierarchy and how it works, and how you need to work with it:
Now You Know the WordPress Template Hierarchy!
Hopefully with this under your belt, you’ve got a pretty good sense of the WordPress template hierarchy: that it’s the way that WordPress interacts with a theme to determine how to build the HTML that it’ll show your site visitors. And hopefully you also understand why WordPress has a template hierarchy (for making themes work with it) and why you’ll use it (to customize the pages of your site, via your theme, more easily). And I hope you also know how to interact with it: by adding or deleting the files that it interacts with. With that, happy hacking!