The Template Hierarchy is a set of rules that WordPress follows when deciding which template file to display. Every time a visitor requests a page, WordPress checks the available template files in your theme and selects the most specific one it can find.
Understanding this template hierarchy, makes building and customizing themes much easier.
Note: A template is a single file that exists within a theme. It is responsible for shaping the layout of either a single page or a set of pages associated with that theme.
Think of Template Hierarchy as a Decision Tree
Imagine a visitor opens a blog post.
WordPress does not immediately load single.php (the default template for blog posts).
Instead, it asks a series of questions:
- Is this a single post?
- Is there a template for this specific post?
- Is there a template for this post type?
- Is there a general single post template?
- Is there a fallback template?
WordPress will keep going down the list until it finds a file that matches.
This process happens for every page request.
Why Does the Template Hierarchy Exist?
Without a hierarchy, every page on a website would need its own custom logic.
The hierarchy allows developers to create general templates that handle many situations while still having the option to create highly specific templates when needed.
For example, you might want:
- One layout for all blog posts
- A different layout for a specific category
- A unique layout for the homepage
The Template Hierarchy makes this possible without writing complex conditions everywhere.
How WordPress Loads the Homepage
The homepage often causes confusion because WordPress supports multiple homepage configurations.
If the site displays recent posts, WordPress checks templates in this order:
home.phpindex.php
If the site uses a static homepage, WordPress checks:
front-page.phppage.phpindex.php
This means a front-page.php file takes priority over almost everything else for the site’s homepage.
Single Posts
When displaying a blog post, WordPress follows a hierarchy similar to this:
single.phpsingular.phpindex.php
For custom post types, the process becomes even more specific.
Suppose you have a custom post type called “portfolio”.
WordPress checks:
single-portfolio.phpsingle.phpsingular.phpindex.php
This allows a portfolio item to have a completely different layout from a regular blog post.
Static Pages
Pages use their own hierarchy.
For a page called “About”:
page-about.phppage-15.phppage.phpsingular.phpindex.php
The number represents the page ID.
This gives developers several ways to target a specific page.
For example: page-contact.php could contain a custom contact page layout without affecting other pages.
Category Archives
When visitors browse a category archive, WordPress searches for templates in this order:
category-news.phpcategory-8.phpcategory.phparchive.phpindex.php
Suppose your website has a category named “News”.
You can create: category-news.php and give it a completely different appearance.
If that file does not exist, WordPress continues down the list.
Tag Archives
Tags follow a very similar pattern.
WordPress checks:
tag-travel.phptag-12.phptag.phparchive.phpindex.php
Again, the most specific template is selected.
Author Archives
When displaying posts from a specific author, WordPress uses:
author-john.phpauthor-3.phpauthor.phparchive.phpindex.php
This allows author pages to have custom layouts when needed.
Search Results
Search pages have their own dedicated template.
WordPress looks for:
search.phpindex.php
If your theme contains: search.php that file controls the search results page.
Without it, WordPress falls back to index.php.
The 404 Page
When visitors request a page that does not exist, WordPress checks:
404.phpindex.php
A custom 404.php allows you to provide helpful navigation, search forms, and links instead of a generic error page.
Archive Templates
Many archive templates share a common fallback.
WordPress often moves through:
archive-projects.phparchive.phpindex.php
This applies to categories, tags, dates, authors, and custom post type archives when more specific templates are unavailable.
A well-designed archive.php can handle many archive views with very little code.
The index.php file. The last resort template
Every classic WordPress theme must contain: index.php
When WordPress can’t find a more specific template, it defaults to index.php. Consider it the safety net for your theme.
A minimal theme could technically work with only:
style.cssindex.php
But that would not be practical.
Because, although that, with only the index.php template our theme could posibly work, every type of content would be rendered by the same template file. As a result, you would lose the main benefit of the Template Hierarchy.
For example, suppose your site contains:
- Homepage
- Blog posts
- Pages
- Search results
- Category archives
- 404 pages
WordPress would load the same template (index.php) for each one of these.
As your site grows, index.php becomes filled with conditional logic:
Now one file is responsible for the entire website.
That creates several problems.
The file becomes difficult to maintain
Imagine opening a 1,000-line index.php six months later.
Finding the code for a specific page becomes tedious.
By comparison, a typical theme might use:
index.php
page.php
single.php
search.php
archive.php
404.php
Each file has one responsibility.
If you want to modify search results, you immediately open: search.php
A real life analogy
A WordPress site with only index.php resembles a hospital with only one doctor.
Every patient goes to that doctor for a broken arm, a heart problem, or eye infection.
The doctor can treat everyone, but eventually things become confusing, and inefficient.
That’s like a WordPress theme with only index.php. Everything is handled in one place.
Now imagine a modern hospital. Here, patients are directed to specialists: Cardiologist, Orthopedist, Ophthalmologist and so on.
The hospital still has a general practitioner as a fallback, but most patients go directly to the most appropriate specialist.
That’s exactly how the Template Hierarchy works.
When a visitor requests: /search/coffee
WordPress asks: Do I have a search.php specialist?
If yes, then search.php handles the request.
For a blog post, single.php is the file that takes control.
For a missing page, 404.php takes over.
And if WordPress can’t find a specialist, only then, it sends the request to index.php which acts like the general practitioner.
The hierarchy is ordered from most specific to least specific.
In our analogy, suppose a patient arrives with a heart condition.
The hospital doesn’t send him to the general practiotioner first.
Instead, it tries first the cardiologist.
Likewise, for a category called “News”, WordPress checks from most specialized to most general.
For example:
category-news.phpcategory.phparchive.phpindex.php
WordPress tries to find the most specialized template available and falls back to more general templates until it reaches index.php.
Where Template Parts Fit In
Template parts are different from template hierarchy files.
Files such as:
header.phpfooter.phpsidebar.phpcontent.php
are usually loaded from other templates using functions like:
get_header();get_footer();get_sidebar();get_template_part();
For example: get_template_part( 'template-parts/content' );
Template parts help organize code, but they are not part of the hierarchy itself.
The hierarchy determines which main template loads. That template can then load smaller reusable pieces.
Tips for Beginners
When creating a theme, start simple.
A common setup includes:
index.phpheader.phpfooter.phppage.phpsingle.phparchive.phpsearch.php404.php
As your theme grows, you can add more specific templates only when needed.
Remember one important rule: The more specific template always takes precedence.
Final Thoughts
The WordPress Template Hierarchy is one of the most important concepts in WordPress theme development. It determines which template file is used for every page request and provides a clear structure for organizing your theme.
At first, the number of template files may seem overwhelming. After a little practice, however, the pattern becomes easy to recognize. WordPress simply starts with the most specific template available and works its way toward index.php. If/When finds a matching file, it stops searching.
Once you understand that process, creating custom layouts, archive pages, search results, and specialized content becomes much easier.
Although my blog doesn’t support comments, feel free to reply via email or X.