What exactly is the WordPress template hierarchy? Sounds complicated, doesn’t it? Don’t worry, it really isn’t that hard to understand.
In short: The template hierarchy for WordPress determines which template file the CMS will use to render each page of your website.
Understood? Cool, then I guess my work is done here. I’m going back to browsing funny cat memes right away.
Then again, since I have a entire afternoon to fill, how about we dive a little deeper into the topic? You know, maybe learn a thing or two. Sound good? Ok, then let’s start from the top.
What are templates?
You have probably heard the term template before, for example in connection with page templates. They are basically files that tell WordPress how to display different types of content on your website. There are template files for posts and pages, as well as archives and attachments.
Now, every time someone requests to see a part of your website by accessing a url, WordPress will figure out which type of content will be displayed and then look for a file to tell it how to do so. Since you can use different templates for different types of content, you can individualize every part of your website.
What is the template hierarchy?
However, many pages on your site can fit into several categories. For example, an archive page both falls into the category of “page” as well as the category of “archive.” If templates exist for both types of content, how does WordPress determine which one it should use?
This is where the WordPress template hierarchy comes into play. It determines the order in which template files are chosen. Every time a request is made to your website, WordPress will go down the hierarchy and serve up the first matching template file.
In the course of this, progression will always be from very specific to increasingly general templates. At the bottom of the entire hierarchy is the index.php file. This template file is required for all WordPress installations and is the default template for your entire website. If no other match can be found, WordPress will skip down to index.php and use it to display the requested page.
To get an overview over the template hierarchy, you can use this interactive diagram.
WordPress template hierarchy for specific content types
As you can see from the diagram, the content hierarchy is not the same for all types of content. Even though in the end they all arrive at the index.php file, the intermediate steps differ greatly from one another. We will therefore go over the template hierarchy for the most important content types in detail. Are you on board? Ok, then.
Home pages
Hierarchy:
- home.php
- index.php
For the display of your homepage — most often the first place users visit when coming to your website — WordPress will usually go with index.php. However, if home.php exists, this template file will take precedent over index.php. Depending on your settings, the homepage of your website can also be rendered by a number of other template files, as you can see below.
Front page
Hierarchy (if homepage displays posts):
- front-page.php
- home.php
- index.php
Hierarchy (if homepage is static):
- front-page.php
- page-{slug}.php
- page-{id}.php
- page.php
- index.php
The front page will display content according to the rules in Settings > Reading. The front-page.php file can therefore be used in two ways: Either to display the latest posts (if you are running a blog-type website) or a static homepage.
For each case the template hierarchy rules are different. When displaying your latest posts, the front page will be treated as a homepage including the homepage template hierarchy. When displaying a static homepage, it is treated as a single page complete with a changed order of templates. You will learn more about the latter below.
Archive pages
Hierarchy:
- archive.php
- index.php
Archive pages display all posts that belong to a certain group. For example all posts from a specific author, in a certain category, or with a specific tag. In absence of a dedicated template file for individual types of archives, WordPress will use the aptly-named archive.php. Failing to find that file, it will fall back on index.php.
Author archives
Hierarchy:
- author-{nicename}.php
- author-{id}.php
- author.php
- archive.php
- index.php
Author pages are a subcategory of archive pages and only show posts published by an individual author. Since it is an archive page, WordPress would use archive.php to render it by default. However, the template hierarchy also allows you to use more specific templates.
For example, lets say a visitor came to your site and wanted to look at all your posts via “http://yoursite.com/author/yourname.” WordPress will then look for a template file for an author page of that name.
Its first intent will be to find a file named author-yourname.php. Failing to do so, it will skip down the hierarchy to the author’s id. For example, if your author id was 5, it would require a template file of the name author-5.php. If that doesn’t exist either, the next possibility is author.php, which you could use to change the design for all author pages on your site.
If none of those files are present, WordPress will then use archive.php or fall back to index.php if even that does not exist.
Category archives
Hierarchy:
- category-{slug}.php
- category-{id}.php
- category.php
- archive.php
- index.php
Category archives work much in the same way as author pages, only instead of ordering posts by author, they will list all posts matched to a specific category. Since category pages belong to archives, archive.php will again be used as a default. This, however, can be overwritten by the presence of more specific template files.
For example, the content found at “http://yoursite.com/category/yourcategory” can be rendered differently in several ways. To only change the content layout for this one category, you can do so via the category slug in the form of category-yourcategory.php or through category-4.php if that category’s id was 4.
In case you don’t want to change the layout for only one category, but still want to make all category archives look different from the content in other archives, you can do so via category.php.
Other archive pages
By now you should have an impression of how the template hierarchy works for WordPress taxonomies. The same holds true not only for category and author pages, but also archives ordered by date, tag, custom post type and custom taxonomy.
Tag archives
Hierarchy:
- tag-{slug}.php
- tag-{id}.php
- archive.php
- index.php
Date archives
Hierarchy:
- date.php
- archive.php
- index.php
Custom post type archives
Hierarchy:
- archive-{post_type}.php
- archive.php
- index.php
You can find also find out more about these templates in the WordPress codex.
Single pages
When talking about single pages we mostly mean static pages (everything that you can create in the WordPress backend under “Pages”) and individual posts which are also displayed as such. Attachment pages for images, videos, and the likes belong to this group as well. For each, the template hierarchy will differ.
Single post pages
Hierarchy:
- single-{post_type_name}.php
- single.php
- index.php
The go-to template file for any type of post is single.php. If only this file is present, every post-like content will use it, including custom post types. If the file cannot be found, as usual the index.php will take over.
However, if you want to customize the template for individual post types, you can do so via single-{post_type_name}.php. For example, if you would like to create a post type called “Product,” you would name your template file single-product.php. Makes sense, doesn’t it?
Pages
Hierarchy:
- Custom page template
- page-{slug}.php
- page-{id}.php
- page.php
- index.php
Pages hold a special position in the WordPress template system because it is possible to assign individual page templates to them manually from the WordPress editor. If a page template has been declared in such a way, it overrides any other template in the hierarchy. In every other case, the standard template file for pages is – unsurprisingly – page.php.
However, it is also possible for individual pages to forestall the usage of page.php via page-{slug}.php or page-{id}.php (in that order). So if you wanted to change the template for a page that lives at “http://yoursite.com/news” and had the page id of 8, you would do so either via page-news.php or with a template file called page-8.php.
Attachment pages
- image.php (or video.php, application.php, text.php, etc.)
- attachment.php
- single-attachment.php
- single.php
- index.php
If you are working with WordPress on a regular basis, you are probably aware that when adding media files to your posts or pages you have the option to include a link to an attachment page upon click. Templates to determine how your media will be displayed to visitors on these pages also exist within the hierarchy, even for each individual type of media.
As you can see, image.php, video.php, etc. can be found at the very top. Should a dedicated file for a single type of media not be present, WordPress will then go for attachment.php as the umbrella template for all types. Next in line is single-attachment.php before WordPress will fall back onto single.php, the standard template for all pages.
Other templates
404 pages
- 404.php
- index.php
You are probably aware that the 404 page is what appears when a page on your website can not be found or a visitors has mistyped a url. If you would like to individualize the appearance of this page, you can do so via 404.php.
Search result pages
- search.php
- index.php
Likewise, if you feel the need to customize the layout of your search results, you can override the standard design by including a template named search.php in your WordPress installation.
The WordPress template hierarchy in a nutshell
The ability to customize almost any part of your website through templates is one of the big advantages of the WordPress platform. By adding template files for different content types, it is possible to individualize pretty much every component.
At that, WordPress’ template hierarchy allows users to get down to the nitty gritty and customize individual posts and pages as well as create umbrella templates for groups of content. At the same time it makes sure that there are always template files to fall back on.
While a few more template files exist in the hierarchy, the ones covered above should be enough to get you started so you can customize your website until your heart’s content.
What are your experiences with the WordPress template hierarchy? Anything to add? Any use cases everyone should know about? Let us know in the comments.
Nick Schäferhoff is an entrepreneur, online marketer, and professional blogger from Germany. He found WordPress when he needed a website for his first business venture and instantly fell in love. When not building websites, creating content or helping his clients improve their online business, he can most often be found at the gym, the dojo or traveling to other countries with his fiancé. If you want to get in touch he would love to hear from you through his website.
6 Comments