Wordpress theme hierarchy

When building a custom WordPress theme, one of the first concepts you’ll encounter is the template hierarchy.

This hierarchy is the system WordPress uses to decide which template file (PHP file) to use for displaying each webpage on your site.

Understanding the template hierarchy is key to customizing how different types of content appear on your website.

In this beginner-friendly guide, we’ll explain what the template hierarchy is, go over core template files like index.php, page.php, single.php, archive.php, and 404.php, and show examples of how WordPress chooses a template for various content types.

We’ll also cover how you can override templates for specific pages, posts, or categories to create a unique design where needed.

What is the WordPress Template Hierarchy?

The WordPress Template Hierarchy is essentially a set of rules that WordPress follows to determine which template file in your theme should be used to render the page you’re trying to view.

WordPress themes are made up of template files (like header.php, footer.php, index.php, etc.), and each file has a specific role. The hierarchy defines the order in which WordPress will look for these files. It starts by searching for the most specific template, and if it doesn’t find it, it falls back to the next one in line.

This continues until a matching template is found. If none of the more specific templates exist, WordPress ultimately falls back to a general template (usually index.php) to display the content.

For example, if a visitor is viewing a blog post, WordPress will first look for a template specifically for that post or post type, then fall back to a more general template if a specific one isn’t available.

This ensures that there’s always a template to fall back on (as long as index.php exists in the theme, which is required for all WordPress themes).

Core Template Files and Their Purpose

WordPress has a number of core template files that serve as the building blocks for your theme’s pages. Here are some of the most important ones for a basic custom theme, and what they are used for:

• index.php – The main fallback template. WordPress uses this if no other, more specific template file is found. Every theme must have an index.php because it is the catch-all for all requests.
• front-page.php – The template for the front page of your site. If you have set a static page as your homepage, or if you’re using the default latest posts on the homepage, WordPress will look for this template first.
• home.php – The template for the blog posts index (your latest posts). If your front page is set to display latest posts, home.php covers that. If you use a static front page, then home.php will be used for the page assigned as the “Posts page” (blog index). If home.php isn’t present, WordPress falls back to index.php for the blog listing.
• single.php – The template for individual single posts (of the default post type). This file is used to display a single blog post. It can also serve as a fallback for any single item of a custom post type (more on custom post types below).
• page.php – The template for individual static pages. This is used for WordPress Pages (like “About Us” or “Contact” pages).
• archive.php – A general template for archive pages (a list of posts). This covers date archives, category archives, tag archives, author archives, or any other type of archive if more specific templates (like category.php or author.php) are not provided.
• category.php, tag.php, author.php, taxonomy.php – Specialized archive templates for specific archive types. For example, category.php is used for category archive pages, tag.php for tag archives, author.php for author archives, and taxonomy.php for custom taxonomy archives. If these specific files are missing, WordPress will fall back to archive.php.
• 404.php – The template for the 404 error page (page not found). If a page doesn’t exist or content can’t be found, this template will be used to show a friendly “Not Found” message.
• search.php – The template for search result pages (the page that shows the results when a user uses the search function).

These files reside in your theme directory. Here’s an example of what a simple theme’s file structure might include:

Don’t worry if you don’t have all of these files in your theme. WordPress doesn’t require each one; it only uses what’s present and falls back through the hierarchy when something is missing. However, having these specific templates allows you to control the look of each type of page separately.

How WordPress Decides Which Template to Use (Examples)

To make sense of the template hierarchy, let’s go through a few common scenarios. We’ll see how WordPress picks the template file, step by step, for each type of content. In each case, WordPress will use the first template file it finds in your theme from the list, and ignore the rest. If it doesn’t find any, it falls back to index.php as the last resort.

1. Displaying the Homepage

The homepage can be configured in two ways: a static front page or as a blog listing of your latest posts. WordPress handles each case slightly differently:

• Static Front Page: If you set a specific Page (in Settings > Reading in your dashboard) to be the front page of the site, WordPress will look for front-page.php first. If front-page.php exists, it uses it for the homepage. If not, it will fall back to the template for a Page:
  1. front-page.php
  2. If not found and the front page is a static page, it will next check page-{slug}.php or page-{ID}.php for that specific page.
  3. If those aren’t found, it uses page.php (the default page template).
  4. If page.php isn’t found, it falls back to index.php.
• Blog Posts Homepage: If your homepage is showing the latest blog posts (the default behavior, or if you set “Your latest posts” as the front page), WordPress will look for a home.php template:
  1. front-page.php (yes, WordPress will still check front-page.php even for the blog posts home; this file, if it exists, overrides any other homepage template).
  2. If front-page.php is not found, then home.php (for the blog listing).
  3. If home.php is not found either, WordPress falls back to index.php.

Example: If you want a custom designed homepage, you might create a front-page.php. If you want a custom design for the blog listing (but not affecting a static front page), you create a home.php.

2. Displaying a Single Blog Post

When a visitor views a single blog post (of the default post type “Post”), WordPress will go through the following sequence to choose a template:

1. single-post.php – a template for the ‘post’ post type specifically. (Since standard blog posts have the post type “post”, WordPress would check for single-post.php.)
2. If that file doesn’t exist, it will look for a generic single post template: single.php.
3. If single.php is not available, (optionally it might check singular.php if your theme has one, which is a generic template for any single post or page).
4. Finally, if none of the above single templates are found, it falls back to index.php.

Note: If you have custom post types (say a post type called “movie”), WordPress would first look for single-movie.php for individual items of that post type. If not found, it would fall back to single.php.

3. Displaying a Static Page

For a static Page (like “About Us” or “Contact”), WordPress uses a similar approach but with page templates:

1. If the page has a unique slug (say “about-us”), WordPress looks for page-about-us.php.
2. If not found, it then checks for a template with the page’s ID, for example page-42.php (if the page ID is 42).
3. If neither a slug-specific nor ID-specific template exists, it falls back to the default page.php template.
4. If page.php isn’t available, it ultimately falls back to index.php.

Example: Suppose you want your “Contact” page (slug “contact”) to have a unique layout. You could create a file called page-contact.php in your theme. WordPress will automatically use that for the “Contact” page instead of the generic page.php.

(Aside: WordPress also allows custom Page Templates with a special comment at the top of a file, which you can assign to pages via the admin. Those are another way to override page layouts on a per-page basis, but that’s slightly different from the automatic hierarchy. In this guide, we’re focusing on the automatic hierarchy rules.)

4. Displaying Category and Archive Pages

Archive pages include categories, tags, custom taxonomies, date archives, author archives – basically any page that lists multiple posts by some grouping or query.

Let’s look at a Category Archive as a common example. Say we have a category called “News” (slug “news”, ID 7). When someone views the “News” category page, WordPress will look for:

1. category-news.php – template for the category with slug “news”.
2. If not found, category-7.php – template for the category with ID 7.
3. If that’s not found, it will use the general category.php template for all categories.
4. If category.php doesn’t exist, it falls back to the catch-all archive template: archive.php.
5. If archive.php is not found either, the final fallback is index.php.

For Tag Archives, the pattern is similar:

1. tag-{slug}.php (e.g., tag-wordpress.php for a tag “wordpress”),
2. then tag-{ID}.php,
3. then tag.php,
4. then archive.php,
5. then index.php.

For Author Archives (posts by a specific author):

1. author-{user_nicename}.php (for a specific author’s username),
2. then author-{ID}.php,
3. then author.php,
4. then archive.php,
5. then index.php.

For Date Archives (year, month, day archives):

• WordPress will look for date.php for any date archive (there aren’t separate default files for year or month; by default it uses the same file for all date-based archives if it exists).
• If date.php is not present, it falls back to archive.php,
• then index.php.

In summary, archives have a hierarchy where they first try the most specific template (like a category-slug file or author-specific file), then the general file for that taxonomy (category.php, author.php, etc.), then the generic archive.php, then index.php.

5. Search Results Page

When a user performs a search on your site and lands on the search results page, WordPress will try to use:

1. search.php – a dedicated template for search result listings.
2. If search.php isn’t found, it falls back to index.php to display the results.

Most themes include a search.php to customize the look of search results separately from a normal archive.

6. 404 Error Page

If a page is not found (a user visits a broken or non-existent link), WordPress displays a 404 error page. The template hierarchy for this is straightforward:

1. 404.php – the template for not-found pages.
2. If 404.php doesn’t exist, WordPress will simply use index.php and likely show a basic “Not found” message from the index loop.

Having a 404.php allows you to design a user-friendly error page (maybe with a search form or links to popular content).

Overriding Templates for Specific Content

One of the powerful features of the template hierarchy is that you can easily override the default templates for specific content to create custom designs. Here are some ways to do that:

• Specific Page Templates by Slug or ID: As mentioned, if you want a specific static page to have its own design, create a template file named after its slug or ID. For example:
  • page-contact.php for the “Contact” page, or
  • page-42.php for the page with ID 42. WordPress will use these files for those pages instead of the generic page.php.
• Specific Category or Tag Templates: Similarly, you can target a particular category or tag:
  • category-news.php for the “News” category,
  • tag-wordpress.php for the “WordPress” tag. This way, that archive page can have a unique layout or style.
• Custom Post Type Templates: If your site has custom post types (like books, portfolio, etc.), you can create templates like single-books.php or archive-portfolio.php to control how those appear. WordPress will automatically use them for the custom post type “books”.
• Child Theme Overrides: If you are modifying an existing theme via a child theme, you can override any template from the parent theme by including a file of the same name in the child theme. For example, to override the parent theme’s archive.php, just add an archive.php in your child theme. WordPress will use the child’s version instead due to the hierarchy (child theme files take precedence).
• Using Conditional Tags in Template Files: If you prefer not to create many different files, you can also use conditional checks within a single file (like index.php or archive.php) to adjust output for different contexts. For example, you might use is_category() in your code to detect a category page and modify the output accordingly. However, using separate template files is often cleaner and easier to maintain.

Example: Imagine you have a category called “Tutorials” for which you want a special banner at the top of the archive page. You can create category-tutorials.php and inside that file, start with <?php get_header(); ?>, then add a custom header/banner only for the Tutorials category, then loop through posts, and finish with <?php get_footer(); ?>. All other categories would still use the regular category.php or archive.php, but the “Tutorials” category will use its own template automatically.

Conclusion and Tips

Understanding the template hierarchy helps you plan and organize your theme files when developing a custom WordPress site. Here are some final tips:

• Start Simple: Begin with an index.php (and of course a style.css with theme info) and maybe a functions.php for your theme. As you need more specialized layouts, add other template files progressively.
• Use the Hierarchy to Your Advantage: Whenever you need a different layout for a certain type of content, remember you can create a new template file with the appropriate name. WordPress will pick it up automatically.
• Reference the Official Diagram: WordPress has an official template hierarchy diagram (available in the WordPress Developer documentation) that visually shows the order of template fallbacks. Keep it handy as a quick reference.
• Child Themes: If you’re customizing an existing theme, use a child theme and leverage the hierarchy to override templates safely without modifying the original theme.
• Test Your Templates: Create a few test posts, pages, categories, etc., and navigate to them to ensure the correct template is being used. If you see a design that doesn’t match what you expected, you might need to create or adjust the appropriate template file.

By using the template hierarchy, you gain fine-grained control over how each part of your WordPress site is displayed, all without writing complex conditional code for every case. It might seem like a lot at first, but with practice, it becomes a natural part of theme development. Happy theming!