WordPress Development

The WordPress Template Hierarchy, Explained for Classic and Block Themes

The WordPress Template Hierarchy, Explained for Classic and Block Themes

A client once asked me why their new “Services” page looked completely different from every other page on their site. They had created it in the editor like any other page, but it displayed with a sidebar, a different header and no featured image. The answer was a file in their theme called page-services.php, created years earlier by a previous developer for an old version of the page. Because the new page had the same slug, WordPress picked that template automatically. That choice is governed by the WordPress template hierarchy.

That’s the WordPress template hierarchy at work. Every time WordPress displays something, it looks for template files in a specific order, from the most specific to the most general, and uses the first one it finds. Once you understand that order, you can create templates precisely where you need them, and you can quickly explain the mysterious behaviour that catches out site owners and developers alike.

The basic idea

WordPress first works out what kind of request it’s handling: a single post, a page, a category archive, a search result, the front page, a 404 and so on. Then it builds a list of possible template names for that request, from most specific to least specific, and checks the theme for each one in turn. The first match wins. If nothing specific exists, it falls back to the most general template: index.php in classic themes or index.html in block themes.

Classic themes use PHP files in the theme folder. Block themes use HTML files in a templates folder, editable in the Site Editor. The hierarchy, the order of preference, is the same for both.

Single posts

For a single blog post, WordPress looks for:

  1. single-post-{slug}.php
  2. single-post.php
  3. single.php
  4. singular.php
  5. index.php

Since WordPress 4.7, you can also create custom templates that editors select per post, using a Template Name header with Template Post Type: post in classic themes, or custom templates registered in theme.json in block themes.

Pages

For a static page:

  1. A custom page template assigned in the editor
  2. page-{slug}.php
  3. page-{id}.php
  4. page.php
  5. singular.php
  6. index.php

This is the hierarchy that caused the Services page surprise. page-services.php matched the slug, so WordPress used it ahead of page.php. Slug-based templates are convenient but easy to forget about. For pages that need a special layout, custom templates selected in the editor are usually clearer, because editors can see and change which template is used.

Custom post types

For a single item of a custom post type such as “case_study”:

  1. single-case_study-{slug}.php
  2. single-case_study.php
  3. single.php
  4. singular.php
  5. index.php

For the post type archive, if has_archive is enabled:

  1. archive-case_study.php
  2. archive.php
  3. index.php

Categories, tags and custom taxonomies

For a category archive:

  1. category-{slug}.php
  2. category-{id}.php
  3. category.php
  4. archive.php
  5. index.php

Tags follow the same pattern with tag-{slug}.php, tag-{id}.php and tag.php.

For custom taxonomies, such as “industry”:

  1. taxonomy-industry-{term}.php
  2. taxonomy-industry.php
  3. taxonomy.php
  4. archive.php
  5. index.php

Authors and dates

Author archives check author-{nicename}.php, author-{id}.php, author.php, archive.php and index.php. Date archives use date.php, then archive.php, then index.php.

The front page and the blog page

These two cause more confusion than anything else.

The front page is your site’s homepage. WordPress checks:

  1. front-page.php
  2. If Settings, Reading is set to show a static page, the page hierarchy for that page
  3. If it’s set to show latest posts, home.php
  4. index.php

The blog posts page is the page showing your latest posts. If your homepage shows latest posts, the front page and the blog are the same. If you’ve set a static homepage and a separate posts page, the posts page uses:

  1. home.php
  2. index.php

Note that home.php is for the blog listing, not the homepage, despite its name. And front-page.php always takes priority for the front page, regardless of reading settings, which surprises people who change their settings and see nothing happen.

Search and 404

Search results use search.php, then index.php. Not-found pages use 404.php, then index.php. Every theme should include a 404 template with helpful navigation.

Attachments

Attachment pages, which WordPress disables by default for new sites since 6.4, follow a hierarchy based on MIME type, such as image.php, then attachment.php, single-attachment-{slug}.php, single.php and so on.

Block themes: same order, different files

In a block theme, templates live in the templates folder as HTML files containing block markup: single.html, page.html, archive.html, front-page.html, home.html, 404.html, search.html, index.html. The hierarchy decides which one is used in exactly the same way.

There’s one crucial difference. Block templates can be edited in the Site Editor, and those edits are saved in the database as wp_template posts, which override the files in the theme. If you edit single.html in the theme folder but someone previously customised the Single template in the Site Editor, your file changes won’t appear. The database version wins.

When debugging block themes, check the Site Editor for customised templates. You can reset a template to the theme’s version from the Site Editor, or export customisations back into theme files.

Template parts, like header and footer, work the same way: files in the parts folder, overridable by database versions.

Child themes

With a child theme, WordPress checks the child theme first for each template in the hierarchy, then the parent. So if the child has page.php and the parent has page-about.php, the parent’s page-about.php still wins for the About page, because it’s more specific. The child’s file only takes priority at the same level of specificity.

This catches developers out. If you want to override a specific template, create the same file name in the child theme.

Debugging which template is used

When a page looks unexpected, find out which template rendered it:

  • Query Monitor shows the template file used and the full list of templates WordPress considered, under its Template panel.
  • In classic themes, you can temporarily print the global $template variable in a development environment.
  • In block themes, the Site Editor shows which template applies when you view or edit a page, and the editor’s template panel for a post shows its assigned template.

Knowing the list WordPress considered is especially helpful, because it tells you exactly which file name to create for a more specific override.

Filters for advanced control

Developers can change template selection with filters such as template_include, which receives the chosen template and can replace it, and {type}_template_hierarchy, which modifies the list of candidates. These are powerful for plugins that provide templates, such as WooCommerce, which uses its own template loading to let themes override its templates.

Use these filters carefully. Overriding templates from a plugin can confuse theme developers who expect the standard hierarchy.

Practical advice

  • Prefer custom templates selectable in the editor over slug-based templates, so the choice is visible.
  • Keep a short list of special templates in your theme documentation.
  • Remove templates you no longer use, so they don’t surprise anyone later.
  • In block themes, remember to check for database customisations before editing files.

The WordPress template hierarchy is one of those foundations that, once learned, makes everything else in theme development clearer. Most “why does this page look different?” questions can be answered in a minute with the hierarchy and Query Monitor.

A worked example

Suppose you want a different layout for case studies in the healthcare industry, where “industry” is a custom taxonomy. On a single case study, WordPress follows the single post type hierarchy, which doesn’t consider taxonomy terms. So taxonomy-industry-healthcare.php would only apply to the healthcare archive page, not to individual case studies.

To change individual case studies by industry, you have several options. In a block theme, create a custom template, such as “Case study, healthcare”, and assign it to those posts. In a classic theme, use the single_template filter to choose a different file when the post has the healthcare term. Or keep one template and vary sections inside it based on the term, which is often the simplest to maintain. Knowing what the hierarchy does and doesn’t consider makes these decisions quick.

Frequently asked questions

What’s the difference between home.php and front-page.php?

front-page.php is always used for the site’s homepage. home.php is used for the blog posts listing, which may or may not be the homepage depending on reading settings.

Do block themes still use PHP templates?

Block themes use HTML templates, though they can include PHP-rendered dynamic blocks. Classic PHP templates are ignored by block themes, except for a few edge cases.

How do I create a template for one specific page?

Create a custom template and select it in the editor, or use page-{slug}.php in a classic theme. The editor approach is easier to manage.

Why aren’t my template file changes showing?

In block themes, a customised version in the Site Editor may be overriding the file. In classic themes, check for a more specific template or a child theme file.