Understanding The WordPress Template Hierarchy

Last Updated on September 22, 2022 by 9 Comments

Understanding The WordPress Template Hierarchy
Blog / Tips & Tricks / Understanding The WordPress Template Hierarchy

In WordPress, pages are stitched together from different template files. Each template file represents another part of the page, and together they make up all of the content of your individual pages, pulled from the WordPress admin. However, which template file is actually selected is based on a fairly robust hierarchy, with a naming convention at it’s root. In this hierarchy, a default template is replaced by template files that are more specific. But this is probably best demonstrated by an example.

Suppose a user visits the page “http://yoursite.com/author/jay”. First, WordPress will search for the template labeled author-jay.php. If that file doesn’t exist, then it looks for author.php. Going up still, it next looks for archive.php. Finally, if this is not found it uses index.php to render the page. Each time a user visits your page, WordPress moves up the template hierarchy until it finds a template file that matches. And this has everything to do with how these files are named.

Template Hierarchy Flow chart

The hierarchy flow for author pages via WP Hierarchy

In this article we will walk through the anatomy of a WordPress theme, and move step by step through the various components of the template hierarchy.

Required Template Files

The first thing to note about a WordPress theme is that certain files are required for a theme to work. These are not all template files, but they all need to exist in order for WordPress to work properly.

For instance, both a functions.php file and a style.css file are required. The former is simply a list of functions that are used to customize WordPress. The latter is a CSS stylesheet which, at the very least, contains basic information about your theme such as name, description and author. Since neither of these are template files we won’t dwell too long on them, but it is useful to know that they exist.

Virtually every other file in your theme directory will be a template file of some kind, which break down into more or less two groups: those that are outside the loop and those that contain the loop. The WordPress loop is used to pull content from your posts and pages and render it on actual pages. These are the files which we will discuss at length, but it’s also worth briefly discussing those files which lie outside of the loop. If you are looking for a good introduction to how the loop works, Kevin Muldoon wrote an excellent article on the subject.

As we move through the various template files that WordPress uses, take special note of their filenames. These filenames are how WordPress knows which template to use and when.

Template Files Outside the Loop

When I refer to files outside of the loop, what I really mean is the components of your page outside of a post or page’s main content, the content entered in the post editor. This includes the content in your header and footer. The header contains all of the HTML and meta information that you want to place before your content. The footer contains everything after.

Appropriately, the header file is called header.php and the footer file is called footer.php. Both of these files are required template files, but exist outside the loop.

Another important template is sidebar.php. This is used for any content outside of the post editor. Often, this lives on the left or right side of the page, but it can actually go anywhere. This is where themes typically display widgets and other extraneous information.

Lastly, comments.php is the template for the comment thread seen at the bottom of most WordPress posts. This file can get quite complex, but in its simplest form, it simply contains some HTML and PHP which indicate how comments should look on your site.

Files outside of the loop are important, but the main structure of a WordPress sites depend on template files that contain actual post content, or those files that exist within the loop. And which template file is selected for each page depends on the order of a template hierarchy, and how files are named within them.

Home Pages

Perhaps the most important page in your WordPress theme is the homepage. When a user visits your homepage, WordPress will look for an index.php file to render the page. But index.php is actually a lot more powerful than that. It is the least specific template file in your hierarchy, and will therefore be used for any page on your site which does not have a template file specified. Archive pages, single pages, etc., all will pull from index.php unless another, more specific template file is included in the theme. We will expand on this a bit more later. For now just remember that index.php is absolutely essential and a required file.

Another file that effects the homepage of your site is front-page.php. If this file is included in a theme, it will override index.php, and take priority when content is rendered on your homepage. There are two ways that front-page.php can be used. The first is to render a list of posts, which is the version you most often see. However, this page can also be used to display a static page. Which one of these is used is determined by your own settings. If you visit Settings -> Reading in the WordPress admin, then you will see the option to either include a list of blog posts or a static page. If you choose the latter option, then you can select which page you want to display.

Keep in mind, index.php and front-page.php can contain exactly the same code, and will render your homepage exactly the same. However, front-page.php will only be used by WordPress on your site’s homepage, while index.php will be used as a default template for all other pages. So, your basic hierarchy for the homepage of your site looks like this (in the order WordPress searches, most specific to least specific):

front-page.php
index.php

As we move through other template files, you will see that this specificity is extremely important to your template hierarchy.

Archive Pages

Archive pages are pages that show a list of posts pulled from a specific group. This includes author pages, category pages, custom post type pages, date pages, and anywhere else where pages are meaningfully grouped together.

The default template for archive pages is titled, not surprisingly, archive.php. If a more specific template file is not indicated for an archive page, then archive.php will be used. Archive.php is not technically required and if it doesn’t exist, then templates will be rendered from index.php. However, it is a good idea to include at least a top level archive.php file with a loop that structures your list. Of course, there are also template files that live deeper in the template hierarchy, which can be used to override the default archive template file.

Archive.php example

The archive.php file in the underscores theme

The hierarchy for basic archive pages is fairly simple:

archive.php
index.php

Author Page

An author page is a subset of an archive which only shows posts from a specific author. For instance, a user may visit “http://yoursite.com/author/jay” and this will show a list of posts written by Jay. By default, this page will use archive.php as its template file. But if you want to get even more specific, you can create a file called author.php. This file will be used to display all author pages and will override the default archive.php file.

But you can get even more detailed and include a file that renders the content for a specific author. This is done by creating a file named either author-[id].php or author-[nicename].php. In the example above, we could create a file called “author-jay.php” and this will override both the archive.php and author.php files for displaying content.

For author pages, you can begin to see how WordPress treats the template hierarchy:

author-[nicename].php
author-[id].php
author.php
archive.php
index.php

Category Page

Category pages work in the same way as author pages. For instance, if we are visiting “http://yoursite.com/category/my-category”, then by default, the archive.php file will be used. But creating a category.php file overrides the default template and is used to render this page. And like author pages, you can also specify a certain category using category-[slug].php or category-[id].php. In both cases, this template will take precedence over the default category template file.

The hierarchy for category pages mirrors that of authors:

category-[slug].php
category-[id].php
category.php
archive.php
index.php

Other Archive Pages

Hopefully the above examples give you a sense of how archive pages work in the template hierarchy. But this does not just apply to author and category pages. In fact, this can be used for any taxonomy in WordPress.

For instance, if I want to create a template file that only applies to tag pages, I could create a file called tag.php, or even tag-[id].php to drill down even more. To create a specific template file for date pages, simply create a file called date.php.

The only exception to this is archive pages for custom post types. Like other taxonomy types, archive.php file will be used. But if you want to use a template for a specific custom post type, then the naming convention is archive-[post_type_name].php. Other than that, this works exactly the same. If you’d like the full list of filenames for archive pages, they are listed in the WordPress codex.

Single Pages

With a firm grasp of how archive pages work, we can move on to the single pages of your WordPress site. These include individual pages like single posts, static pages, attachment posts, and individual posts in custom post types.

Post Pages

Post pages refer to any individual pages that fall in the “Posts” post type, or in a custom post type that you created. The general template for individual posts is the single.php file. If only a single.php file is included, then all individual posts, including individual attachment posts and custom post types, will be displayed using this template. The single.php file is not required, and if one is not included, then the index.php file will be used.

Single PHP file example

The single.php file in the underscores theme

If you want to specify a template for the post of a specific post type, then you can use the single-[post_type_name].php naming convention. If your post type were called “Portfolio” for instance, then a custom template file should be called single-portfolio.php.

It is also possible to be more specific with attachment pages, by using attachment.php to specify how attachments should look. You can even get more detailed than that by indicating a specific MIME type for attachments, such as image.php or video.php. In the end, the hierarchy for single posts looks like this:

image.php (or video.php, text.php, etc.)
attachment.php
single-attachment.php
single-[post_type_name].php
single.php
index.php

Pages

Pages are a special case, and refer to those individual pieces of content that live in the “Pages” post type in the WordPress admin. Like other content types, you can specify a default template by creating a template file called page.php. Like the others, this file is not required, and if absent, then index.php will be used. Page.php will only render templates for pages.

Unlike single posts, it is actually possible to create a template for a very specific page by either using page-[id].php or page-[slug].php. These template files only will apply to the single page they are assigned to. All others will be rendered with page.php.

But pages also feature a full template system. WordPress page templates are fairly complex, but they are used to create different layouts that can easily be applied to pages through a drop-down menu in the admin. Kevin Muldoon wrote a great article about how they work. If you specify a specific template, then this will override any other template files in the hierarchy. So, if you choose a template for Page ID 4, but you also have a page-4.php file, then the template you chose will be used, not page-4.php.

The general order for pages looks like this:

custom template
page-[slug].php
page-[id].php
page.php
index.php

Other Templates

The template files discussed above cover most of the pages that will be displayed on any WordPress site. However, there are a couple of outliers to take note of. The first is the 404.php file, which will be displayed whenever a page cannot be found or a user mistyped your URL. I wrote a post about how to handle 404 pages with custom templates.

Another page which you might sometimes see is search.php. This is the template that will be used when search results are displayed. However, this is also sometimes handled in the index.php file of a theme.

Diving Into the Template Hierarchy

The WordPress template hierarchy is more of a reference than anything else. There is a strict naming convention that you need to follow, but it all kind of falls into place as you move through theme development or customization. If you want a quick guide, you can always visit the interactive chart at WP Hierarchy which tells you which template files are used and when.

In premium and custom coded themes, you will probably see a level of complexity that extends even beyond the parameters discussed in this articles. This sometimes means breaking chunks of content into individual content fragment files, or specifying a series of templates that are distributed throughout the system. However, using the template hierarchy as a guide, it can be fairly simple to understand how a theme comes together, and more importantly, where you can tweak it.

Article thumbnail by Dvoishnik / shutterstock.com

Divi

Want To Build Better WordPress Websites? Start Here! 👇

Take the first step towards a better website.

Get Started
Divi
Premade Layouts

Check Out These Related Posts

Splice Video Editor: An Overview and Review

Splice Video Editor: An Overview and Review

Updated on March 10, 2023 in Tips & Tricks

Video is a valuable form of content for social media. Unfortunately, creating quality videos is usually a long process that involves moving mobile footage to a desktop app for editing. However, mobile editing is on the rise. Apps such as Splice Video Editor make it possible to efficiently create...

View Full Post
How to Use Font Awesome On Your WordPress Website

How to Use Font Awesome On Your WordPress Website

Updated on September 16, 2022 in Tips & Tricks

When given the choice between using a vector icon or a static image, it’s a good idea to go with the vector. They’re small and fast to load, and they can scale to any size without a loss of resolution. Font Awesome is a superb library of vector icons that you can use on your websites,...

View Full Post

9 Comments

  1. Hello Jay,
    How do I override the default “Read More” On the post thumbnails when a page lists the posts related to a category? Like I want to put in custom information in each post thumbnail, so it shows the thumbnail picture, title, a dynamic donation progress bar, as seen on gofundme.com? I’ve installed the Give Donations Plugin

    Thank you

  2. great article.

    One of the pages i have is generating the 404 template, thinking it is a category which doesnt exist. it would be great to know which template was suppose to be loaded right before the 404 one.

  3. Really great post Jay. Thanks for putting this together.

  4. Very informative article. Thanks for sharing!

  5. Great starter for me as a newbie to WordPress. I can now start messing around with the code and see what I can creat, Lovely! 🙂

  6. Hiyak! Thanks Hoffman, learning great from ur tips! Cheers.

  7. I am developing my first WP theme and this post is a great resource for me.

    Thanks for taking the time to share your knowledge with us 🙂

  8. Great post Jay! Thanks for sharing… 🙂

  9. Great post and goes some way to helping people understand how CMS systems work. All this of course can affect SEO – it is something we discussed over on our Divi Facebook page and it would be interesting to hear your views on no follow and no index of specifically tag, archive, search and categories.

    Great post!

    AP

Leave A Reply

Comments are reviewed and must adhere to our comments policy.

Get Started With Divi