Wondering about WordPress template hierarchy – as of now in 2025? Well, WordPress hasn’t changed how it picks templates for years. Then block themes showed up and shook things up.
Suddenly, the files live in a new folder. They’re written in HTML, not PHP. And some of the rules – while still mostly the same – look different in practice. That’s where people get confused.

This post clears things up. It explains how WordPress decides which file to load for a page, both in classic and block themes. I’ll show where the templates go, what WordPress looks for first, and how it moves down the list when files are missing.
If you’re building or editing a theme, this is what you need to know first.
What is the WordPress template hierarchy?
When someone visits any page on your WordPress website, WordPress has to somehow decide what to show. “Like, duh, captain obvious!” Yeah, I know, but hear me out:
So WordPress checks the URL, figures out what kind of page it is, and then picks a template file to load.
This is called the template hierarchy. It’s a ranked list of file names that tell WordPress which part of the template/theme to use. WordPress starts at the top and works down until it finds a file that exists in your theme.
Quick example: Let’s say someone visits a blog post of yours. WordPress will look for the single.php
file, then singular.php
, and finally index.php
. The first one it finds wins.
The same idea works for pages, categories, tags, archives – pretty much every kind of view.
Each type of page has its own list, however. You don’t have to include every file in your theme. WordPress just skips anything that’s missing.
At the bottom of every list is the mighty index
file. It’s the fallback. That’s why every theme must have it.
This system has been in WordPress for years. It works the same way for both classic and block themes, even though the file types and folder locations can be different.
The classic theme template hierarchy
Classic themes use .php
files to control how WordPress pages are displayed. These files live in the root folder of the theme. The most basic one is index.php
. It’s required. Every other template is optional.
File structure and extensions
In a classic theme, templates are written in PHP. Each file matches a specific kind of page. You’ll commonly see files like:
page.php
– for pagessingle.php
– for individual postsarchive.php
– for archive pages and post listingshome.php
– for the homepage404.php
– you know what this issearch.php
– for search results
They all sit at the top level of the theme folder. No special subfolders are used.
How WordPress chooses a template
WordPress looks at the URL (or rather on the query string), figures out what kind of content is being requested, and then checks a list of template names in a set order. This order is called the template hierarchy.
It always starts with the most specific file and works down to the most general. The first match it finds is used.
Example: On a category page, WordPress checks for:
category-{slug}.php
category-{id}.php
category.php
archive.php
index.php
If it finds a template for category-dogs.php
(and the category to be displayed is “dogs,” of course), it stops there. If that file doesn’t exist, it keeps moving down the list until it finds a template that does and uses that.
Master Modern WordPress Development 🏆
Get ‘Modern WordPress Fast Track’ today
Become a WordPress Developer Who Can Build Anything
Learn to build high-value block themes and plugins with AI and automation in a focused 10-week course. By the end, you’ll master block themes and plugins, leverage AI assistance, implement automated testing, optimize for scale, and confidently deploy professional WordPress solutions.
Presale is currently open with 40% OFF until May 23rd, 2025. 🚀
Course starts June 1st.
We have prepared special bonuses for everyone who enrolls during this period! 🎁
Common template types
Here are a few other template hierarchies you’ll see in classic themes:
- Single post:
single-{post-type}-{slug}.php
→single-{post-type}.php
→single.php
→singular.php
→index.php
- Pages:
custom template file
→page-{slug}.php
→page-{id}.php
→page.php
→singular.php
→index.php
- Tags:
tag-{slug}.php
→tag-{id}.php
→tag.php
→archive.php
→index.php
- Front page:
front-page.php
→home.php
→page.php
→index.php
- Search results:
search.php
→index.php
Every page type has its own chain. All of them end at index.php
.
Child themes and overrides
If you’re using a child theme, then any template files set in it can override templates in the parent theme.
- If both themes have
archive.php
, for example, then WordPress uses the one from the child theme. - For another example, if the child theme adds a specific file like
category-dogs.php
, then that file takes priority over what’s in the parent theme. However, if the parent hascategory-dogs.php
and the child only hascategory.php
, the more specific file in the parent will still be used.
Here’s the official visualization of the entire template hierarchy in classic themes:

Use this chart to see which files WordPress looks for, and in what order. It’s your map through the hierarchy.
The block theme template hierarchy
Block themes work differently from classic themes. Not just in terms of how they work in the WordPress UI, but also when it comes to the template hierarchy.
The rules are mostly the same on the fundamental level, but the setup and file types have changed:
How it differs structurally from classic themes
Block themes don’t use PHP files for templates. They use .html
files. These files go inside a /templates/
folder, not the root.
The only required file is index.html
. Everything else is optional.
WordPress checks three places for block templates:
- Templates saved in the database (
wp_template
posts). - A child theme’s
/templates/
folder if child theme is active). - The main theme’s
/templates/
folder.
It uses the first match it finds, just like with classic themes.
Templates saved in the database
As mentioned above, WordPress first looks up if the template to be used hasn’t been saved in the database.
This is a new feature available in block themes.
The way it works is that if you want to customize your site, the Site Editor lets you add custom templates and template parts.
When you create a template, the Site Editor will walk you through setting up the hierarchy for that template. While it doesn’t actually use the term “template hierarchy” for these steps, the choices that you make connect directly to the template hierarchy.
For example, let’s say that you want to create a template for your site’s category archive. When you create the category template through the Site Editor, you’ll see two options:

- All Categories – this will be the default fallback template to list category items. This will be used unless there’s a more specific template.
- Category – this lets you create a dedicated template for a certain category. This template is more specific than the All Categories template, so it will take priority.
WordPress will explain this hierarchical relationship in plain text when you’re creating the template:

In consequence, you can also overriding templates for individual pieces of content this way.
What you can do in the Site Editor is create a special template for a single piece of content, for example.
When you do this, this special template will take priority over any other applicable templates in the template hierarchy. That is, the post that you apply the template to will always use that template, regardless of any other templates that you’ve created that might apply.
You can create these custom templates from the main Site Editor, as well as from the editor for the individual piece of content to which you want to apply that template.
For example, if you’re working in the Site Editor, you can add a new template and apply it to a specific post on your site:

While you can achieve something similar using a “traditional” WordPress theme, it’s a bit more complicated because you would first need to add a PHP file for that template to your theme and then choose the template from the post editor.
File hierarchy behavior
The way WordPress chooses templates still follows the same old template hierarchy. It checks the type of page (post, page, category, etc.) and then works down a list of possible file names.
Example: For a blog post on a block theme, WordPress checks:
{custom-template}.html
single-{post_type}-{post_name}.html
single-{post_type}.html
single.html
singular.html
index.html
Just like classic themes, the first file it finds is used. If none are found, index.html
is the fallback.
Key template types and fallbacks
Here are a few common chains in block themes:
- Page:
{custom-template}.html
→page-{post_name}.html
→page-{id}.html
→page.html
→index.html
- Post:
{custom-template}.html
→single-{post_type}-{post_name}.html
→single-{post_type}.html
→single.html
→singular.html
→index.html
- Category:
category-{slug}.html
→category-{id}.html
→category.html
→archive.html
→index.html
- Search:
search.html
→index.html
- 404:
404.html
→index.html
One unique part of the hierarchy worth going through separately is the front page hierarchy. The official docs say that the hierarchy can change “drastically” (their word) depending on what the user has chosen for their front page settings in wp-admin. Two main cases:

- If “Your latest posts” chosen as the front page:
front-page.html
→home.html
→index.html
- If “A static page” chosen as the front page:
front-page.html
→{custom-template}.html
→page-{post_name}.html
→page-{post_id}.html
→page.html
→index.html
Here’s the official visualization of the template hierarchy in block themes:

This chart shows the order WordPress follows when loading templates in any block theme.
How to check the template of a block theme
One nice thing about how the Site Editor interacts with the WordPress template hierarchy is that it makes it really easy to see which template a piece of content is using.
For example, if you create a blog post, it will use your site’s Single template by default and indicate this in the Template setting of the Post sidebar:

Classic theme hierarchy vs block theme hierarchy
Here’s a quick table that should make it easier to grasp the main differences between how classic themes and block themes handle the WordPress template hierarchy:
Detail | Classic themes | Block themes |
---|---|---|
File extension | .php | .html |
File location | Root directory | /templates/ folder |
Template storage | Files only | Files + database (wp_template ) |
Required file | index.php | index.html |
Layout control | PHP templates with functions | Block markup (no PHP logic) |
The inner structure of template files for classic and block
One thing you might have noticed in the table above is that last row – layout control. So what does that mean, actually?
Let’s take a look into some default themes in WordPress: the old but still popular Twenty Twenty (classic theme), and one of the best new default themes Twenty Twenty-Four (block theme).
Here’s the bigger part of the singular.php
file of the Twenty Twenty theme:
<?php
get_header();
?>
<main id="site-content">
<?php
if ( have_posts() ) {
while ( have_posts() ) {
the_post();
get_template_part( 'template-parts/content', get_post_type() );
}
}
?>
</main><!-- #site-content -->
<?php get_template_part( 'template-parts/footer-menus-widgets' ); ?>
<?php
get_footer();
Code language: PHP (php)
Ignoring the logic of how this template handles its job, the main thing to pay attention to is that this is a classic PHP file with some HTML mixed in here and there.
Now for comparison, let’s look at the single.html
file from the Twenty Twenty-Four theme:
<!-- wp:template-part {"slug":"header","area":"header","tagName":"header"} /-->
<!-- wp:group {"tagName":"main","align":"full"} -->
<main class="wp-block-group alignfull">
<!-- wp:group {"style":{"spacing":{"padding":{"top":"var:preset|spacing|50"},"margin":{"bottom":"var:preset|spacing|40"}}},"layout":{"type":"constrained"}} -->
<div class="wp-block-group"
style="margin-bottom:var(--wp--preset--spacing--40);padding-top:var(--wp--preset--spacing--50)">
<!-- wp:post-featured-image {"style":{"spacing":{"margin":{"bottom":"var:preset|spacing|40"}}}} /-->
<!-- wp:group {"style":{"spacing":{"blockGap":"var:preset|spacing|10","padding":{"top":"0","bottom":"0"}}},"layout":{"type":"flex","orientation":"vertical","justifyContent":"stretch"}} -->
<div class="wp-block-group" style="padding-top:0;padding-bottom:0">
<!-- wp:post-title {"level":1,"fontSize":"x-large"} /-->
<!-- wp:template-part {"slug":"post-meta"} /-->
</div>
<!-- /wp:group -->
</div>
<!-- /wp:group -->
<!-- wp:post-content {"lock":{"move":false,"remove":true},"align":"full","layout":{"type":"constrained"}} /-->
<!-- wp:group {"style":{"spacing":{"margin":{"top":"var:preset|spacing|40"},"padding":{"bottom":"var:preset|spacing|50"}}},"layout":{"type":"constrained"}} -->
<div class="wp-block-group"
style="margin-top:var(--wp--preset--spacing--40);padding-bottom:var(--wp--preset--spacing--50)">
<!-- wp:post-terms {"term":"post_tag","separator":" ","className":"is-style-pill"} /-->
<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
<!-- wp:spacer {"height":"var:preset|spacing|40"} -->
<div style="height:var(--wp--preset--spacing--40)" aria-hidden="true" class="wp-block-spacer">
</div>
<!-- /wp:spacer -->
<!-- wp:separator {"style":{"spacing":{"margin":{"bottom":"var:preset|spacing|40"}}},"backgroundColor":"contrast-3","className":"is-style-wide"} -->
<hr class="wp-block-separator has-text-color has-contrast-3-color has-alpha-channel-opacity has-contrast-3-background-color has-background is-style-wide" style="margin-bottom:var(--wp--preset--spacing--40)"/>
<!-- /wp:separator -->
<!-- wp:pattern {"slug":"twentytwentyfour/hidden-comments"} /-->
<!-- wp:pattern {"slug":"twentytwentyfour/hidden-post-navigation"} /-->
</div>
<!-- /wp:group -->
</div>
<!-- /wp:group -->
</main>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","area":"footer","tagName":"footer"} /-->
Code language: HTML, XML (xml)
A lot more code, that’s for sure, but the important part is that most of the template’s job is handled through the WordPress block editor comments.
Things like: < !-- wp:pattern {"slug":"twentytwentyfour/hidden-comments"} /-->
or < !-- wp:template-part {"slug":"post-meta"} /-->
.
This is more or less the main difference in the inner structure of block template files compared to classic files. However, when it comes to the template hierarchy itself, that, again, works basically the same.
Simplifying the hierarchy for beginners
The template hierarchy sounds complex at first. But it follows one simple idea:
👉 WordPress looks for the most specific file and keeps going until it finds one. That’s it.
The fallback rule
Every list of possible templates ends with the fallback. That’s the index.php
file for classic themes, and index.html
for block themes.
Tips for new developers
- Always include an
index
file. It’s the only one you must have. - You don’t need to build every possible file when crafting a theme. Add more files when needed to change how different pages look.
- Use real pages on your site to test how the hierarchy works.
In classic themes, you can use PHP and WordPress functions. In block themes, you work with blocks only – no PHP logic inside templates.
- Need more control in classic themes? Use Conditional Tags in your PHP.
- Want cleaner layouts in block themes? Use template parts and patterns to split up your design.
Start simple. Add only what you need. The hierarchy will still do the work for you.
Conclusion
WordPress doesn’t pick templates at random – this is the main thing we’ve learned! It follows a clear order, based on the kind of page someone’s visiting. That’s the template hierarchy.
Classic themes use PHP files. Block themes use HTML files. The file names and folder locations may change, but the core idea stays the same: start with the most specific file, fall back if it’s not there.
You don’t need to know every rule. Just know how WordPress thinks. That’s enough to start editing themes or building your own.
When in doubt, check the charts above, make a test page, and see what file WordPress loads.
This is the system behind every WordPress page. Once you get it, everything else makes more sense.
Plus, you can always have a glance into the official docs – linked below.
And if you still have any questions about the WordPress template hierarchy, let us know in the comments!
…
Don’t forget to join our crash course on speeding up your WordPress site. Learn more below:
- Classic hierarchy https://developer.wordpress.org/themes/basics/template-hierarchy/ ↩︎
- Block hierarchy https://developer.wordpress.org/themes/templates/template-hierarchy/ ↩︎