Template Hierarchy Explained (With Real Examples)

WordPress template hierarchy determines which template file is loaded for a given URL. Understanding this system is essential for theme development, customization, and debugging issues like “why is this page using the wrong layout?”

This guide explains the WordPress template hierarchy step by step, with real, practical examples you’ll actually encounter when building or customizing themes.

---

What Is the Template Hierarchy?

The template hierarchy is a fallback system. For every request, WordPress checks for the most specific template first. If it doesn’t exist, WordPress falls back to more general templates — until it finally uses index.php.

Think of it as:

“Use the most specific file available. If not found, use the next best option.”

---

The Absolute Fallback: index.php

index.php is required in every WordPress theme. If no other template matches, WordPress will always use it.

index.php  ← last resort

If your site works but layouts look wrong, it often means WordPress is falling back to index.php.

---

Single Post Template Hierarchy

When viewing a single post, WordPress checks templates in this order:

single-{post_type}-{slug}.php
single-{post_type}.php
single.php
singular.php
index.php

Real Example: Blog Post

URL:

https://example.com/hello-world/

Post type: post

WordPress looks for:

• single-post-hello-world.php
• single-post.php
• single.php
• singular.php
• index.php

Tip: Use single.php for general posts, and single-{post_type}.php for CPTs.

---

Custom Post Type (CPT) Single Templates

Custom post types follow the same rules, but with their post type slug.

Example: CPT = product

single-product.php

This template will be used for all single product posts.

If you want to target a specific product:

single-product-sample-item.php

---

Page Template Hierarchy

Pages have their own hierarchy, and it’s slightly different from posts.

page-{slug}.php
page-{id}.php
page.php
singular.php
index.php

Real Example: About Page

Page slug: about

WordPress checks:

• page-about.php
• page-42.php (if page ID is 42)
• page.php
• singular.php
• index.php

Best practice: Use page-{slug}.php for landing pages with unique layouts.

---

Custom Page Templates (Selectable in Admin)

You can also create custom page templates selectable from the editor.

/*
Template Name: Full Width Landing
*/

This template overrides the hierarchy when selected.

Priority:

Custom page template → Page hierarchy → index.php

---

Archive Template Hierarchy

Archives include categories, tags, CPT archives, author archives, and date archives.

Post Type Archive

archive-{post_type}.php
archive.php
index.php

Example: CPT = event

archive-event.php

Used for:

https://example.com/event/

---

Category Archive Hierarchy

category-{slug}.php
category-{id}.php
category.php
archive.php
index.php

Example: Category = news

• category-news.php
• category-7.php
• category.php

---

Tag Archive Hierarchy

tag-{slug}.php
tag-{id}.php
tag.php
archive.php
index.php

---

Taxonomy (Custom Taxonomy) Hierarchy

Custom taxonomies have their own hierarchy.

taxonomy-{taxonomy}-{term}.php
taxonomy-{taxonomy}.php
taxonomy.php
archive.php
index.php

Example: Taxonomy = genre, Term = rock

• taxonomy-genre-rock.php
• taxonomy-genre.php

---

Author Archive Hierarchy

author-{nicename}.php
author-{id}.php
author.php
archive.php
index.php

---

Search Results Hierarchy

search.php
index.php

If your search results look wrong, check whether search.php exists.

---

404 Error Page Hierarchy

404.php
index.php

Always create 404.php for better UX and SEO.

---

Visual Summary (Mental Model)

You can think of the hierarchy like this:

Most specific template
↓
Less specific template
↓
Generic template
↓
index.php

WordPress always prefers specificity.

---

How to Debug Which Template Is Being Used

Use one of these methods:

• Install Query Monitor → shows the active template
• Add temporary debug output:

add_action( 'wp_footer', function() {
  global $template;
  echo '<!-- ' . esc_html( $template ) . ' -->';
});

This prints the template path in the HTML source.

---

Best Practices for Template Hierarchy

• Use archive-{post_type}.php for CPT listings
• Use single-{post_type}.php for CPT detail pages
• Avoid overusing index.php
• Name templates clearly and intentionally
• Keep hierarchy simple — don’t over-fragment unless needed

---

Conclusion

The WordPress template hierarchy is predictable, powerful, and developer-friendly once you understand it. By knowing exactly which file WordPress looks for — and in what order, you can control layouts with precision and debug theme issues quickly.

Key takeaway:
Create the most specific template you need — WordPress will handle the rest.

Mastering the template hierarchy is a major step toward professional WordPress theme development.

🎨 Want to learn more? Visit our WordPress Customization Hub for tips and advanced techniques.