Your guide to the WordPress template hierarchy: what you need to know

Whether you know it or not, the WordPress template hierarchy determines how WordPress displays your site's content, and why some pages have a different design than others.

Essentially, the WordPress template hierarchy helps WordPress decide which of your theme's template files to use for every single piece of content on your site.

If you plan to develop WordPress themes, or plugins, it's essential to understand the template hierarchy. And even if you're just an end-user, understanding the template hierarchy can also help you make meaningful changes to your site.

For example, you can use the WordPress template hierarchy to create a special archive layout for a custom post type or a dedicated archive page for a specific author on your site.

In this post, you'll learn everything you need to know about the WordPress template hierarchy, starting with a basic introduction to its function and importance, and building up to some more advanced tips to put the template hierarchy to work.

We'll also include a detailed breakdown of the exact template hierarchy for key WordPress content, like single posts and archive pages. You can use this easy-to-follow cheat sheet to quickly understand how the template hierarchy fits together.

What is the WordPress template hierarchy? More detail

Your WordPress site's content is not all the same. You have:

*Pages

*Posts

*Your blog post page that lists all your latest posts (called an archive)

*Archives for individual authors, categories, and tags

*Search pages

*404 pages

*Etc.

While the exact styling of those WordPress pages depends on which theme you’re using (and its HTML and CSS), there's a pretty good chance that each one of those pages has a different design.

To change the design for different types of content, WordPress theme developers can include a variety of template files. For example, a theme developer might include one template file for blog posts but another template file for static pages.

In order for that to work across the thousands of WordPress themes in existence, WordPress needs a standardised way to match each piece of content with the right template file. It needs to be able to say:

Blog posts should use Template A

Pages should use Template B, etc.

At a very high level, the WordPress template hierarchy is just a standardized process to help WordPress make those decisions no matter what theme is being used.

Why does the WordPress template hierarchy exist?

In order for WordPress to pick the proper template for each piece of content on your site, it needs to balance two factors:

1. It needs to be easy for theme developers or end-users to create templates that target specific types of content. After all, you probably don't want to use the exact same template for every piece of content on your site.

2. It needs a fallback template so that, if there isn't a specific template for a piece of content, there's always at least one template that WordPress can use.

The WordPress template hierarchy ensures that, no matter what, each piece of content on your site has a template. Otherwise, you might run into odd situations where some content is completely unstyled and doesn’t match the rest of your site.

How does the WordPress template hierarchy work?

The WordPress template hierarchy is basically a list of yes/no questions that WordPress goes through when it renders each piece of content.

When WordPress needs to display a piece of content, it starts by looking for the most specific template (according to the hierarchy, which we'll cover next).

If that template doesn't exist, WordPress will move on to the next most specific template, and so on.

The last choice in this process is always your site's index.php file. Basically, index.php is the absolute fallback for any piece of content.

If WordPress can't find a more specific template file to use, it will just display the content using index.php.

Let's look at an example to drive home the point.

Let's say WordPress is trying to display the archive template for a specific taxonomy on your site. In this case, it's a list of posts that are tagged with "Sports". The tag's slug is "sports" and its ID is "6".

When WordPress selects the template for that tag archive page, it will ask a series of Yes/No questions to find the right template file, starting with the most specific option and, if all the answers are "No", eventually ending up at index.php:

*Does the template file tag-sports.php exist (a dedicated template file for the "sports" slug)? If yes, display that. If no, move to the next option.

*Does the template file tag-6.php exist (a dedicated template file for the tag's ID)? If yes, display that. If no, move to the next option.

*Does the template file tag.php exist (the generic template file for all tags)? If yes, display that. If no, move to the next option.

*Does the template file archive.php exist (the generic template file for any WordPress archive page)? If yes, display that. If no, move to the next option.

*Index.php — if none of the other template files exist, the default fallback is always index.php.

The hierarchy connects child themes to parent themes

The WordPress template hierarchy also helps you connect a WordPress child theme to a parent theme.

If you're using a child theme on your WordPress website, WordPress will first check your child theme for templates before moving on to the parent theme.

If a child theme has an equally (or more) specific template, WordPress will use the child theme's template file instead of the parent theme.

If the parent theme has a more specific template, WordPress will still use the parent theme's template, though.

For example, if both the parent and child theme had a tag-sports.php template, WordPress would use the child theme template.

On the other hand, if the parent theme has tag-sports.php but the child theme only has tag.php, then WordPress would still use the tag-sports.php template file from the parent theme because it's higher up in the hierarchy than the tag.php template file in the child theme.

The full WordPress template hierarchy for different types of content

Now, let's get a little more detailed and look at the actual template hierarchy that WordPress applies to different types of content on your site.

That is, we'll look at the decision list that WordPress goes through for each type of content, starting with the most specific template and always ending at index.php (remember — index.php is the universal fallback template for all content).

The hierarchy for each content goes in this order:

1. Most specific template
2. Next most specific template
3. …
4. Index.php (least specific template)

If you're a theme developer, it's important to understand this information so that you can properly create an optimised design. And if you're an end-user, understanding these hierarchies will make it easier for you to customise your site.

We'll divide this into six different sections:

1. Single post or custom post type

2. Single page

3. Site front page

4. Archives

5. Search results page

6. 404 error page

7. Single post

This hierarchy determines how WordPress displays an individual post. This includes both Posts (blog posts) and any custom post types that you might be using:

1. single-{post-type}-{slug}.php — a specific post within a specific post type. E.g. single-event-bonnaroo-festival.php

2. single-{post-type}.php — a specific post type. E.g. single-event.php.

3. single.php

4. singular.php — the default for all singular items (including posts, pages, and custom post types).

5. Index.php

The addition of post type templates in WordPress 4.7 also allows developers to display different templates based on the choices a user makes in the WordPress editor.

WordPress also has a dedicated hierarchy just for the attachment post type:

1. {mime-type}.php — the MIME type of a file. E.g. image.php, video.php, etc.

2. attachment.php

3. single-attachment-{slug} — a template for a specific file attachment. E.g. single-attachment-holiday.php.

4. single-attachment.php — a template for all single attachments.

5. single.php

6. singular.php

7. index.php

8. Static page

To determine the template for a static page, WordPress uses the following hierarchy:

*Custom page template — a custom template that users can select from the editor.

*page-{slug}.php — a specific page slug. E.g. page-about-us.php to create a dedicated "About Us" page template.

*page-{id}.php — a specific page ID. E.g. page-12.php.

*page.php — default template for all static pages.

*singular.php

*index.php

1. Site front page

The static homepage template hierarchy is a little tricky because it depends on whether or not you've chosen to use a static front page (Settings → Reading in your WordPress dashboard).

No matter what, WordPress always checks for the front-page.php template first.

If front-page.php does not exist and you're using a static front page, WordPress follows the page template hierarchy from the previous section.

If front-page.php does not exist and you're listing your blog posts on the front page, WordPress follows this template hierarchy:

1. home.php

2. index.php

3. Archives

WordPress uses a different template hierarchy depending on the specific type of archive it's displaying:

Category archives:

1. category-{slug}.php — an archive for a specific category slug. E.g. category-news.php.

2. category-{id}.php — an archive for a specific category ID. E.g. category-12.php.

3. category.php — the default template for all category page archives.

4. archive.php — the default template for all archives.

5. index.php

Tag archives:

*tag-{slug}.php — an archive for a specific tag slug. E.g. tag-news.php.

*tag-{id}.php — an archive for a specific tag ID. E.g. tag-12.php.

*tag.php — the default template for all tag archives.

*archive.php

*index.php

Custom taxonomy archives:

1. taxonomy-{taxonomy}-{term}.php — an archive for a specific custom taxonomy term. E.g. a "Basketball" term in a "Sport" taxonomy would be taxonomy-sport-basketball.php.

2. taxonomy-{taxonomy}.php — an archive for all terms in a specific taxonomy. E.g. taxonomy-sport.php.

3. taxonomy.php — the default template for all custom taxonomy archives.

4. archive.php

5. index.php

Custom post type archives

1. archive-{post_type}.php — a dedicated archive for a specific custom post type. E.g. archive-event.php for an "Event" post type.

2. archive.php

3. index.php

Author archives

1. author-{nicename}.php — a dedicated archive for a specific author nice name. E.g. author-james.php.

2. author-{id}.php — a dedicated archive for a specific author ID. E.g. author-12.php.

3. author.php — the default archive for all authors.

4. archive.php

5. index.php

Date-based archives

1. date.php — the default template for all date-based archives.

2. archive.php

3. index.php

4. Search page

5. search.php — the default template for all search results.

6. index.php

There's also a separate searchform.php template that is the default way to display a search form.

404 page

1. 404.php — a dedicated 404 error page template.

2. index.php

How to tell which template a piece of content is using

If you want a fast way to understand which template a piece of content is using, you can use the free Which Template File plugin at WordPress.org.

With the plugin enabled, you can browse to any piece of content on your site and instantly see which template file it's using on the WordPress toolbar.

For example, you can see that a page in the default Twenty Twenty theme uses the singular.php template. Because WordPress made it all the way to the singular.php template, that means the Twenty Twenty theme does not include a dedicated page.php template for static pages. If it did, WordPress would use that instead because page.php is further up the hierarchy.

This is also a great tool to learn more about the template hierarchy because it lets you connect real content on your website with the underlying template files.

Manipulating the WordPress template hierarchy

Understanding the default WordPress template hierarchy is essential for developing themes and/or customizing your website.

But once you learn the basics, you might want to be able to manipulate, or "hack", the default WordPress template hierarchy on a case-by-case basis.

Here are some advanced tips for manipulating the WordPress template hierarchy to suit your needs using WordPress hooks or other tweaks.

Override more specific parent templates from a child theme

Let's say you have a parent theme with category.php and a child theme with just archive.php (no category.php).

Because category.php is more specific, WordPress would still use the template from your parent theme for category archive pages.

If you wanted to override this to use your child theme's archive.php template, you can just create a simple child theme category.php template file with the following code:

<?php

// Duplicate archive.php

include 'archive.php';

Now, you can still use your child theme's archive.php template for category archives without needing to duplicate your child theme's archive.php code in the category.php template.

Skip the template loader

If you want to perform an action before WordPress determines which template to load, you can use the template_redirect hook.

For example, you could use this to restrict access to your site, like automatically redirecting non-logged in users to your login page if they try to access certain types of content.

Or, you can stop your theme from loading entirely, which is helpful if you're creating some type of API.

Get started with the WordPress template hierarchy on the best WordPress hosting

The WordPress template hierarchy helps WordPress determine which template file to use when it loads content.

If you're venturing into theme development, it's important to understand the WordPress template hierarchy so that you can design your themes in an optimal way. And if you're a WordPress end-user or developer, understanding the template hierarchy will help you customise your site as needed, like creating a dedicated template for a custom post type.

To get started with the WordPress template hierarchy on the best WordPress hosting, click here to learn more about tsoHost's dedicated WordPress hosting plans.