Introduction to the WordPress Template Hierarchy

One of the key questions that WordPress users ask at some time in their life is the following: how do WordPress themes manage to show different pages depending on the content we are seeing?

The question, besides being totally legit, is very interesting. WordPress is able to identify what content it’s about to render and, depending on its type, use one template or the other. WordPress themes are nothing more than a set of specific templates for each content type with some JavaScript for dynamic elements and CSS for styles and colors.

Perfect, but… how do WordPress templates actually work? This is what we are going to see step by step throughout this post.

Before we start, though, let me show you a picture with the answer to this question:

This is the WordPress template hierarchy. You can find all the information about it in the WordPress Codex, the official documentation. You can even interact with this hierarchy in this cool website.

Basically, WordPress uses a hierarchy of templates to render its contents. That is, WordPress searches within the theme that you have active for a specific PHP file. If it exists, WordPress renders the content using that file, which we call template. If it doesn’t, WordPress looks for the next most-generic template within the hierarchy. If it exists, WordPress uses it. Otherwise, WordPress looks for the next template in the hierarchy… and so on. If WordPress cannot find a specific template file in your theme, it uses the default index.php file, the most generic of all templates.

Now, let’s go deep into more detail within the template hierarchy of some of the most common WordPress content.

Page Templates

Let’s see the templates that WordPress uses for rendering pages and simple content types.

Posts and Custom Post Types

WordPress looks at the following PHP files on your theme to render a blog post or a custom post type:

single-{post-type}-{slug}.php: if you want a specific template for a specific post or a specific post type, you have to create this PHP file in your theme. Its name includes the post type name ({post-type}), which can be post or anything else (product, if you use WooCommerce). And you must also type the slug or permalink, call it what you want, in the name of the template. For example, if I want to use a specific template for this post, I would have to create the single-post-introduction-to-the-wordpress-template-hierarchy.php file.
single-{post-type}.php: if we want to affect all content of a specific post type (all posts or all products), we will use this template, whose name only includes the name of the post type.
single.php: WordPress uses this template to render any single content (a specific post, a specific product, etc).
singular.php: this is another top-level template to render single content of any kind.
index.php: if none of the above was found, WordPress uses this generic template to render your content.

Remember that in the WordPress theme directory you have thousands of examples of WordPress themes at your disposal. I recommend that you download one and try, as a learning exercise, to inspect its PHP files and identify the templates that I just presented.

By doing so you can understand what templates they use within the hierarchy of WordPress templates and see what content each of these templates has. With no doubt, if you want to learn about WordPress themes, this is something mandatory to do. Furthermore, it’s free!

Nelio Content

I’m so happy about Nelio Content that I will sound like a payed advocate… but here’s why you’ll love it: it works as promised, its auto-scheduling feature is top-notch, Nelio’s value for money is unmatched, and the support team feels like your own.

Panozk

WordPress.org

View Plans

Regular Pages

As with posts and other post types, WordPress uses a hierarchy of templates to render pages:

Selected template: if from the page attributes box when editing a page you select a specific template, it always takes priority over all the others. You can learn to create custom templates here.
page-{slug}.php: if you want a specific page to have its own template, create that template in a PHP file that has the slug of the page in the name.
page-{id}.php: you can also directly use the WordPress page ID where the template is applied.
page.php: this template applies to all WordPress pages, unless one of the previous templates in the hierarchy has already been applied.
singular.php: the singular template is the default template for all pages, posts, products, and so on. This template will rarely be applied since most themes in WordPress already include a page.php template.
index.php: as always, this is WordPress’ default fallback template.

Now try to check again the theme you downloaded before and you will see that now you understand a little more the other files that appear there. Surely you can now identify PHP files for page templates.

Special Pages

In WordPress there are other special pages that also make use of specific templates to render content. An example of this is the main page of the website. Remember that the main page is selected in the WordPress Settings, within the Reading submenu. The following template hierarchy is used for that page:

front-page.php: if you use a static page as the main page in WordPress, it will first try to apply the front-page.php template.
home.php: if the previous template is not found, WordPress tries to use this template. This template is also used if instead of selecting a static page as the main page you have selected the option to show your latest posts.
index.php: again, the default template is always present.

The page that shows the search results of your WordPress is also a special page that can have its own template. To do this you can use the search.php template. If your theme does not define it, index.php will be used as usual.

Finally, the page shown when your website returns a 404 error can also be configured with a specific WordPress template. You have to create the 404.php file in your theme and then this template will be applied.

Templates for Archives

So far we have seen templates for single content (except in the case of search results). But in WordPress there are also archives, which might render more than one element in a page. Let’s see what hierarchy of templates WordPress uses in this case.

Categories and Tags

WordPress uses the following template hierarchy for categories:

category-{slug}.php: this template is used to render the list of content (usually posts) that belong to a specific category. In particular, it’ll be used when rendering the category whose slug appears in the name of the PHP file.
category-{id}.php: if you prefer to use category IDs instead of slugs you can also do it. For example, if you want to apply a template to category 13, create the template file with the name category-13.php.
category.php: the default template for all categories.
archive.php: this is the most generic template for archives in WordPress.
index.php: again, if your theme doesn’t include a more specific template, WordPress will default to this file.

The following template hierarchy is used for tags:

tag-{slug}.php: if the tag is called interview, we can use the tag-interview.php template in case we want to design a specific template for that tag in WordPress.
tag-{id}.php: we can also define the template through the tag ID.
tag.php: as with category.php, this is the generic template for tags.
archive.php: again, this template will be used if none of the above exists.
index.php: as always, this is the fallback template.

Custom Post Types and Custom Taxonomies

If we have custom content types we can use the template archive-{post_type}.php where post_type is the slug of the custom post type. This will render the list of contents for that post type.

For custom taxonomies, WordPress uses the following template hierarchy:

taxonomy-{taxonomy}-{term}.php: if you have a custom taxonomy called videogames in WordPress and want to create a template with a specific design for the term sports within that taxonomy, you will have to create the file taxonomy-videogames-sports.php to use that template.
taxonomy-{taxonomy}.php: if you want to use the same template for all taxonomy terms, simply use taxonomy-videogames.php, in the previous example.
taxonomy.php: this is the default template for all taxonomies.
archive.php: if none of the above templates exist, this applies.
index.php: again, this is the default fallback template.

With all these explanations you should already have everything you need to create and identify templates in your WordPress themes.

To Sum Up

Understanding the hierarchy of WordPress templates is key to being able to understand the themes and even develop your own. It never hurts to take a look at this and know how it works to gain confidence when you start modifying the PHP code of the theme that you use in our WordPress.

There are some other templates, but less often used. Anyway, remember that you can always go to check the WordPress Codex documentation. There you will find everything that was not explained here.

What do you think of all this? Are you still using templates for your WordPress content or are you already building all the designs with blocks? Do not forget to leave me a comment below if you have reached the end of the post—I would love to know how you use WordPress templates!

Featured image by Edvard Alexander Rølvaag on Unsplash.