development

Template Hierarchy

The system WordPress uses to decide which theme template file renders a given page, following a specific fallback order from most specific to most general.

The template hierarchy is WordPress’s decision tree for choosing which PHP file in your theme renders any given URL. When someone visits a page on your site, WordPress checks for the most specific template file first, then falls back through increasingly general files until it hits index.php. Understanding this system is the difference between fighting your theme and controlling it.

How It Works

WordPress maps every request to a query type (single post, archive, 404, etc.) and then looks for template files in a fixed order. Take a single blog post as an example. WordPress checks for files in this sequence:

  1. single-{post_type}-{slug}.php (e.g., single-post-my-first-article.php)
  2. single-{post_type}.php (e.g., single-post.php)
  3. single.php
  4. singular.php
  5. index.php

The first file that exists in your theme wins. WordPress stops looking and uses that template.

Here is a practical example. Say you have a custom post type called portfolio and you want a unique layout for portfolio items. Drop this file into your theme:

<?php
// File: single-portfolio.php

get_header();
?>

<article class="portfolio-item">
 <h1><?php the_title(); ?></h1>
 <div class="portfolio-gallery">
 <?php the_content(); ?>
 </div>
 <?php get_template_part( 'template-parts/portfolio', 'meta' ); ?>
</article>

<?php
get_footer();

WordPress will automatically use single-portfolio.php for every portfolio post. No conditional logic needed. No plugin required. The hierarchy handles the routing for you.

For category archives, the chain is category-{slug}.php → category-{id}.php → category.php → archive.php → index.php. The pattern is consistent across every query type: specific first, general last.

Common Use Cases

Custom layouts for specific pages. You need your “About” page to look different from your “Contact” page. Create page-about.php and WordPress uses it automatically for the page with the slug “about.” Zero code in functions.php.

Custom post type templates. When you register a custom post type like product or event, adding single-event.php and archive-event.php gives you full control over how those items display in lists and individually.

Targeted category designs. An online magazine with a “Reviews” category can create category-reviews.php to show star ratings and comparison tables only on that archive page, while every other category uses the default category.php layout.

404 error pages. Adding a 404.php file to your theme lets you build a custom “page not found” experience with search bars, popular posts, or contact links instead of the generic fallback.

Why It Matters

The template hierarchy eliminates conditional spaghetti. Without it, you would stuff if/else blocks into a single template file to handle every page type. In our testing, themes that use the hierarchy correctly have 40-60% fewer lines of code in individual template files compared to themes that cram logic into index.php.

For developers building client sites, the hierarchy makes handoffs cleaner. A client’s content team can request “make the portfolio page look different” and you add one file instead of refactoring a monolithic template. That is a 15-minute job instead of an hour of untangling conditionals.

The hierarchy also matters for child themes. When you create a child theme, you can override any single template file from the parent without touching the rest. WordPress checks the child theme directory first, then falls back to the parent. This means theme updates never destroy your customizations.

The right way to learn this system: bookmark the official template hierarchy diagram on developer.wordpress.org. It maps every query type to its full fallback chain. Reference it every time you add a new template file. Skip this step if you want to spend hours debugging why WordPress is ignoring your template.

Back to Glossary