WordPress Template Hierarchy: Complete Visual Map & Fallback Logic

When a visitor navigates to a URL on a WordPress website (such as example.com/category/tutorials/ or example.com/about/), how does WordPress decide which PHP template file in your active theme directory should render the page? It follows a strictly deterministic, visual decision tree known as the WordPress Template Hierarchy. Understanding this hierarchy allows theme developers to craft bespoke layouts for specific categories, authors, custom post types, or individual landing pages with surgical precision.

Figure 30.1: WordPress Template Hierarchy Resolution Flowchart

The Fundamental Fallback Philosophy

The Template Hierarchy works on a simple principle: from most specific to most generic. WordPress first searches your active theme directory for the most specific file name matching the query. If that file is absent, it moves down the branch to a slightly broader template, continuing down until it reaches the ultimate universal fallback: index.php.

The 7 Primary Template Branches

1. Single Blog Post (Singular Post Page)

When viewing a single blog article (e.g. example.com/learn-php/), WordPress traverses this chain:

1. single-post-{post-slug}.php (e.g., single-post-learn-php.php)
2. single-post.php (Targeting all standard posts)
3. single.php (Targeting all single items, including CPTs)
4. singular.php (Shared fallback for both single posts and static pages)
5. index.php

2. Static Page Hierarchy

When viewing a static page (e.g. example.com/about-us/ with page ID 42):

1. Custom Page Template: If the author selected a custom template from the Page Attributes dropdown (e.g. template-fullwidth.php).
2. page-{slug}.php (e.g., page-about-us.php)
3. page-{id}.php (e.g., page-42.php)
4. page.php
5. singular.php
6. index.php

3. Category Archive Hierarchy

When viewing a category archive (e.g. example.com/category/news/ with term ID 7):

1. category-{slug}.php (e.g., category-news.php)
2. category-{id}.php (e.g., category-7.php)
3. category.php
4. archive.php (Universal archive for categories, tags, authors, and dates)
5. index.php

4. Custom Post Type (CPT) Hierarchy

If you register a custom post type called portfolio:

• Single CPT Item: single-portfolio-{slug}.php → single-portfolio.php → single.php → singular.php → index.php.
• CPT Archive (/portfolio/): archive-portfolio.php → archive.php → index.php.

5. Front Page vs. Home Page (The Subtle Difference)