WordPress Template Hierarchy Explained (original) (raw)

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.

1. What is the WordPress template hierarchy?
2. The classic theme template hierarchy
   1. Master Modern WordPress Development
3. The block theme template hierarchy
4. Classic theme hierarchy vs block theme hierarchy
5. The inner structure of template files for classic and block
6. Simplifying the hierarchy for beginners

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 pages
• single.php – for individual posts
• archive.php – for archive pages and post listings
• home.php – for the homepage
• 404.php – you know what this is
• search.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:

1. category-{slug}.php
2. category-{id}.php
3. category.php
4. archive.php
5. 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.

OPEN FOR ENROLLMENT

Master Modern WordPress Development

Learn to build high-value block themes and plugins with AI and automation in this professioanl WordPress development 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.

Join Modern WordPress Fast Track today!

02:04 min • Watch the course overview

BLACK FRIDAY SALE: GET 35% OFF

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 has category-dogs.php and the child only has category.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:

1. Templates saved in the database (wp_template posts).
2. A child theme’s /templates/ folder if child theme is active).
3. 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:

1. All Categories – this will be the default fallback template to list category items. This will be used unless there’s a more specific template.
2. 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:

1. {custom-template}.html
2. single-{post_type}-{post_name}.html
3. single-{post_type}.html
4. single.html
5. singular.html
6. 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:

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:

`