If you have ever opened a WordPress theme folder and wondered which file actually controls the page you are looking at, you are not alone. Most developers building their first custom theme start by editing files at random, hoping something changes. The good news: WordPress follows a strict, predictable system called the WordPress template hierarchy, and once you understand it, theme development becomes far less frustrating.
In this guide, we will walk through how WordPress decides which template file to load, give you a clean visual breakdown from front-page.php all the way down to index.php, and explain how to apply this knowledge when building your own themes.
What Is the WordPress Template Hierarchy?
The WordPress template hierarchy is the ranked list of template files that WordPress checks, in order, to figure out which file should render the current page. When a visitor requests a URL, WordPress identifies the type of content being requested (a single post, a category archive, a page, the homepage, etc.) and then looks through your active theme for the most specific template file available.
If WordPress finds a match, it uses that file. If it does not, it falls back to a more generic template. The fallback chain always ends at index.php, which is the only template file truly required in a classic WordPress theme.
In short: WordPress goes from most specific to most general until it finds a file that exists.
Why Understanding the Hierarchy Matters
- You stop editing the wrong file and wondering why nothing changes.
- You write less code by leveraging fallbacks instead of duplicating logic.
- You build cleaner, more maintainable custom themes.
- You can target very specific pages (a single category, a custom post type, a specific page slug) without plugins or hacks.
How WordPress Picks a Template File: The Process
- WordPress parses the request URL and runs the main query.
- It determines the query type (is this a single post? an archive? the front page?).
- It generates a list of candidate template files based on that query type.
- It scans your active theme folder for those files in order, from most specific to most generic.
- The first matching file wins. If none match,
index.phpis used.
Visual Breakdown of the WordPress Template Hierarchy
Here is a clear table showing what WordPress looks for, depending on the type of content being displayed.
Front Page and Home
| Order | Template File | When It’s Used |
|---|---|---|
| 1 | front-page.php |
Always used for the front page if it exists, regardless of settings. |
| 2 | home.php |
Used for the blog posts index page. |
| 3 | index.php |
Final fallback. |
Single Posts
| Order | Template File | When It’s Used |
|---|---|---|
| 1 | single-{post-type}-{slug}.php |
A specific post by slug for a specific post type. |
| 2 | single-{post-type}.php |
All posts of a custom post type. |
| 3 | single.php |
Any single post. |
| 4 | singular.php |
Any singular content (post or page). |
| 5 | index.php |
Final fallback. |
Pages
| Order | Template File | When It’s Used |
|---|---|---|
| 1 | Custom Page Template | Selected from the editor sidebar. |
| 2 | page-{slug}.php |
A specific page by slug (e.g. page-about.php). |
| 3 | page-{id}.php |
A specific page by ID. |
| 4 | page.php |
All pages. |
| 5 | singular.php |
Any singular content. |
| 6 | index.php |
Final fallback. |
Category, Tag and Taxonomy Archives
| Order | Template File | When It’s Used |
|---|---|---|
| 1 | category-{slug}.php |
Specific category by slug. |
| 2 | category-{id}.php |
Specific category by ID. |
| 3 | category.php |
All categories. |
| 4 | archive.php |
Generic archive. |
| 5 | index.php |
Final fallback. |
The same logic applies to tags (tag-{slug}.php, tag.php) and custom taxonomies (taxonomy-{taxonomy}-{term}.php, taxonomy-{taxonomy}.php, taxonomy.php).
Other Common Templates
- Search results:
search.phpthenindex.php - 404 errors:
404.phpthenindex.php - Author archives:
author-{nicename}.php,author-{id}.php,author.php,archive.php,index.php - Date archives:
date.php,archive.php,index.php - Attachments:
{mime-type}.php,attachment.php,single-attachment.php,single.php,singular.php,index.php
A Real Example: Which File Loads When?
Imagine you have a custom post type called portfolio, and a visitor lands on a portfolio item with the slug marketing-redesign. WordPress will look, in order, for:
single-portfolio-marketing-redesign.phpsingle-portfolio.phpsingle.phpsingular.phpindex.php
This is incredibly powerful. Want a totally unique layout for one specific portfolio entry? Just create the most specific file. Want all portfolio items to share a layout? Create single-portfolio.php. Want all single content to look the same? Use single.php. You only build what you need.
Block Themes vs Classic Themes
The hierarchy described above applies to classic PHP themes. Block themes (introduced with full site editing) follow the same conceptual hierarchy, but the templates live in the /templates/ folder as HTML files (e.g. single.html, archive.html, index.html) and template parts live in /parts/. The naming rules and fallback chain remain the same, which means everything you learn here transfers directly.
Practical Tips for Theme Developers
- Start with
index.phpand add specificity only when needed. - Use
get_template_part()to share code between templates instead of duplicating it. - If you are unsure which template is loading, install a debug plugin or temporarily echo
get_page_template()in your footer. - Name files exactly as documented. A typo in
single-portfolio.phpwill silently make WordPress fall back tosingle.php. - Use the
template_includefilter for advanced custom logic when standard naming is not enough.
Common Mistakes to Avoid
- Editing
index.phpwhen you should editsingle.php. If a more specific file exists,index.phpis never even loaded. - Forgetting that
front-page.phpoverrideshome.php. If your blog index suddenly shows the wrong layout, check for a strayfront-page.php. - Using IDs in template names. Slugs are safer because IDs change between environments.
- Assuming page templates and
page-{slug}.phpare the same thing. They are not. Custom page templates are selected manually in the editor, whilepage-{slug}.phpis automatic.
FAQ
What is the only required file in a WordPress theme?
For classic themes, index.php and style.css are the only strictly required files. For block themes, index.html, style.css and theme.json are required.
Does the template hierarchy work the same in block themes?
Yes. The naming and fallback rules are identical, but the files live in /templates/ and use the .html extension instead of .php.
How can I check which template file WordPress is loading?
You can use a plugin like Query Monitor, or simply add <?php echo basename(get_page_template()); ?> temporarily inside your footer to see the current template file name.
What happens if two specific templates exist for the same content?
WordPress always picks the most specific one first. For example, single-portfolio-marketing-redesign.php will always beat single-portfolio.php.
Can I use the same template logic with custom post types and taxonomies?
Absolutely. Custom post types follow the single-{post-type}.php pattern, and custom taxonomies follow taxonomy-{taxonomy}-{term}.php. This is one of the most powerful features of the hierarchy.
Wrapping Up
The WordPress template hierarchy is not magic, it is just a deterministic lookup system. Once you internalize the order in which WordPress searches for files, building custom themes becomes a matter of creating only the templates you need and letting the fallbacks handle the rest. Bookmark the tables above, keep them next to your editor, and you will never edit the wrong file again.
At Markup Dude, we convert designs into pixel perfect, hierarchy aware WordPress themes every day. If you need a hand turning your next mockup into a clean, maintainable theme, get in touch.
