WordPress Template Hierarchy — Every Template File Explained with Examples

In this tutorial, you'll learn the WordPress template hierarchy — how WordPress chooses which template file to use for every page type, with visual diagrams and practical examples for customizing any template.

What You'll Learn

• What the template hierarchy is and why WordPress uses a fallback system
• Front page hierarchy (front-page.php -> page.php -> index.php)
• Single post hierarchy (single-{post-type}-{slug}.php -> single.php -> singular.php -> index.php)
• Page hierarchy (page-{slug}.php -> page-{id}.php -> page.php -> singular.php -> index.php)
• Category hierarchy (category-{slug}.php -> category.php -> archive.php -> index.php)
• Tag hierarchy (same fallback pattern)
• Author hierarchy (author-{nicename}.php -> author.php -> archive.php -> index.php)
• Date hierarchy (date.php -> archive.php -> index.php)
• 404 template (404.php -> index.php)
• Search results template (search.php -> index.php)
• Custom post type archives (archive-{posttype}.php -> archive.php -> index.php)
• Custom taxonomy archives (taxonomy-{taxonomy}-{term}.php -> taxonomy-{taxonomy}.php -> taxonomy.php -> archive.php -> index.php)
• Embed template (embed.php -> embed-{posttype}.php -> embed-{format}.php)
• Using the hierarchy to customize specific pages

Why It Matters

The template hierarchy is the single most important concept in WordPress theme development. When a Visitor requests a page, WordPress follows a strict order of template file checks. Understanding this order means you know exactly which file to create or edit for any customization. Without it, you are guessing. With it, you can target a single page, a category, an author archive, or any specific view with surgical precision.

Real-World Use

A news site wants a different layout for their "Technology" category (with a sidebar) than for their "Opinion" category (full width). Using the hierarchy, the developer creates category-technology.php for the tech archive and category-opinion.php for opinion. WordPress automatically uses the correct template when visitors browse each category. No conditionals, no plugins, no complex logic.

Learning Path

flowchart LR
  A[Theme Anatomy] --> B[Installing Themes]
  B --> C[Full Site Editing]
  C --> D[Customizer]
  D --> E[Widgets]
  E --> F[Menus]
  F --> G[Child Themes]
  G --> H[Template Hierarchy]
  H --> I[CSS Customization]
  style H fill:#4a90d9,color:#fff

Visual Template Hierarchy Overview

flowchart TD
    REQ[Page Request] --> PT{Page Type?}
    PT -->|Front Page| FH[front-page.php]
    PT -->|Single Post| SH[single-{post-type}-{slug}.php]
    PT -->|Page| PH[page-{slug}.php]
    PT -->|Category| CH[category-{slug}.php]
    PT -->|Tag| TH[tag-{slug}.php]
    PT -->|Author| AH[author-{nicename}.php]
    PT -->|Date| DH[date.php]
    PT -->|404| NF[404.php]
    PT -->|Search| SH2[search.php]
    PT -->|Attachment| ATT[attachment.php]

    FH -->|No| FHF[page.php]
    SH -->|No| SHF[single-{post-type}.php]
    PH -->|No| PHF[page-{id}.php]
    CH -->|No| CHF[category-{id}.php]
    TH -->|No| THF[tag-{id}.php]
    AH -->|No| AHF[author.php]
    DH -->|No| DHF[archive.php]
    NF -->|No| NFF[index.php]
    SH2 -->|No| SH2F[index.php]
    ATT -->|No| ATTF[attachment.php fallbacks]

    FHF -->|No| FHF2[singular.php]
    SHF -->|No| SH2F2[single.php]
    PHF -->|No| PHF2[page.php]
    CHF -->|No| CHFF[category.php]
    THF -->|No| THFF[tag.php]
    AHF -->|No| AHFF[archive.php]

    FHF2 -->|No| FINAL[index.php]
    SH2F2 -->|No| SHFIN[singular.php]
    PHF2 -->|No| PHFIN[singular.php]
    CHFF -->|No| CHFFF[archive.php]
    THFF -->|No| THFFF[archive.php]
    AHFF -->|No| AHFINAL[index.php]

    SHFIN -->|No| LAST[index.php]
    PHFIN -->|No| PLAST[index.php]
    CHFFF -->|No| CL[index.php]
    THFFF -->|No| TL[index.php]

Every arrow ending in index.php means WordPress falls back to the catch-all template.

Front Page Hierarchy

When a visitor lands on your site's homepage, WordPress checks in this order:

1. front-page.php — The most specific front page template
2. page.php — Only used if "A static page" is set in Settings > Reading, and the chosen front page is a page
3. index.php — The universal fallback

Examples

• front-page.php — Use for a custom homepage with hero section, features, testimonials
• page-home.php or page-{slug}.php — If you want a page-specific layout
• index.php — The default blog feed layout

// front-page.php
<?php get_header(); ?>
<main class="home-hero">
    <h1>Welcome to My Site</h1>
    <p>This is the custom front page template.</p>
</main>
<?php get_footer(); ?>

Single Post Hierarchy

When viewing a single post, WordPress checks:

1. single-{post-type}-{slug}.php — e.g., single-post-hello-world.php
2. single-{post-type}.php — e.g., single-post.php or single-book.php (for custom post types)
3. single.php — Generic single post template
4. singular.php — Used for both single posts and pages
5. index.php — Universal fallback

Examples

• single-post.php — Custom layout for all standard posts
• single-product.php — Custom layout for WooCommerce products
• single-post-hello-world.php — Layout for one specific post (rare but possible)

// single.php
<?php get_header(); ?>
<main id="primary" class="site-main">
    <?php while ( have_posts() ) : the_post(); ?>
        <article <?php post_class(); ?>>
            <h1 class="entry-title"><?php the_title(); ?></h1>
            <div class="entry-content"><?php the_content(); ?></div>
        </article>
    <?php endwhile; ?>
</main>
<?php get_sidebar(); ?>
<?php get_footer(); ?>

Page Hierarchy

When viewing a static page:

1. page-{slug}.php — e.g., page-about.php, page-contact.php
2. page-{id}.php — e.g., page-42.php (where 42 is the page ID)
3. page.php — Generic page template
4. singular.php — Shared template for singular content
5. index.php — Universal fallback

Practical Example: Custom About Page

If you have an "About" page with slug "about", create page-about.php:

<?php
/* Template Name: About Page Custom */
get_header();
?>
<main class="about-page">
    <div class="about-hero">
        <h1><?php the_title(); ?></h1>
    </div>
    <div class="about-content">
        <?php the_content(); ?>
    </div>
</main>
<?php get_footer(); ?>

WordPress automatically uses this file when the "About" page is viewed.

Category Hierarchy

When viewing a category archive:

1. category-{slug}.php — e.g., category-news.php, category-technology.php
2. category-{id}.php — e.g., category-5.php
3. category.php — Generic category template
4. archive.php — Generic archive template
5. index.php — Universal fallback

Full Width vs Sidebar by Category

// category-news.php — Full width layout
<?php get_header(); ?>
<main class="full-width">
    <h1><?php single_cat_title(); ?></h1>
    <?php while ( have_posts() ) : the_post(); ?>
        <article><?php the_title(); ?></article>
    <?php endwhile; ?>
</main>
<?php get_footer(); ?>

// category-opinion.php — With sidebar
<?php get_header(); ?>
<main class="with-sidebar">
    <h1><?php single_cat_title(); ?></h1>
    <?php while ( have_posts() ) : the_post(); ?>
        <article><?php the_title(); ?></article>
    <?php endwhile; ?>
</main>
<?php get_sidebar(); ?>
<?php get_footer(); ?>

Tag Hierarchy

Same pattern as categories but with tag- prefix:

1. tag-{slug}.php — e.g., tag-JavaScript.php
2. tag-{id}.php — e.g., tag-12.php
3. tag.php — Generic tag template
4. archive.php — Generic archive template
5. index.php

Author Hierarchy

1. author-{nicename}.php — e.g., author-johndoe.php
2. author-{id}.php — e.g., author-3.php
3. author.php — Generic author template
4. archive.php — Generic archive template
5. index.php

// author.php
<?php get_header(); ?>
<main class="author-archive">
    <h1>Articles by <?php the_author(); ?></h1>
    <?php while ( have_posts() ) : the_post(); ?>
        <article><?php the_title(); ?></article>
    <?php endwhile; ?>
</main>
<?php get_footer(); ?>

Date Hierarchy

1. date.php — Custom date archive template
2. archive.php — Generic archive template
3. index.php

404 Template

1. 404.php — Custom 404 page
2. index.php — Falls back to main template

// 404.php
<?php get_header(); ?>
<main class="error-404 not-found">
    <h1>Page Not Found</h1>
    <p>Sorry, we could not find what you were looking for.</p>
    <?php get_search_form(); ?>
</main>
<?php get_footer(); ?>

Search Results

1. search.php — Custom search results template
2. index.php

// search.php
<?php get_header(); ?>
<main class="search-results">
    <h1>Search Results for: <?php echo get_search_query(); ?></h1>
    <?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
        <article><?php the_title(); ?></article>
    <?php endwhile; else : ?>
        <p>No results found.</p>
    <?php endif; ?>
</main>
<?php get_footer(); ?>

Custom Post Type Archives

For archive pages of custom post types:

1. archive-{posttype}.php — e.g., archive-product.php, archive-portfolio.php
2. archive.php — Generic archive template
3. index.php

Single Custom Post Type

1. single-{posttype}-{slug}.php — e.g., single-product-widget.php
2. single-{posttype}.php — e.g., single-product.php
3. single.php — Generic single template
4. singular.php
5. index.php

Custom Taxonomy Archives

1. taxonomy-{taxonomy}-{term}.php — e.g., taxonomy-genre-sci-fi.php
2. taxonomy-{taxonomy}.php — e.g., taxonomy-genre.php
3. taxonomy.php — Generic taxonomy template
4. archive.php — Generic archive template
5. index.php

Embed Template

WordPress 4.4+ supports oEmbed. The template hierarchy for embeds:

1. embed-{posttype}-{format}.php
2. embed-{posttype}.php
3. embed.php
4. index.php

Using the Hierarchy to Customize Specific Pages

Practical Workflow

1. Determine what page type you are targeting (single, page, category, author).
2. Identify the most specific template file from the hierarchy.
3. Create that file in your child theme.
4. Customize the markup.
5. Test the specific page or archive.

Debugging Which Template Is Loaded

Add this to your theme's functions.php for debugging:

function my_template_debug( $template ) {
    if ( current_user_can( 'manage_options' ) ) {
        echo '<!-- Template: ' . basename( $template ) . ' -->';
    }
    return $template;
}
add_filter( 'template_include', 'my_template_debug', 1000 );

View the page source — an HTML comment shows the template filename.

Alternatively, use the Query Monitor plugin. It shows which template file was used on every page load in the admin toolbar.

Creating Template Files for a Child Theme

When using a child theme to override templates:

1. Identify the parent template file path (e.g., parent/single.php).
2. Create the same path in the child theme (e.g., child/single.php).
3. Modify as needed.
4. WordPress uses the child's version automatically.

This works for any template in the hierarchy: category.php, page.php, archive.php, header.php, footer.php, and all others.

Common Mistakes

1. Creating the wrong template filename — A typo in the hierarchy (e.g., catagory-news.php instead of category-news.php) means WordPress ignores your file. Double-check spelling and hyphenation.

2. Assuming all page types have unique templates — WordPress falls back to index.php eventually. If you only have index.php, every page type uses it. Create specific templates for better control.

3. Overriding templates in the parent theme instead of a child theme — Editing the parent's template files means updates overwrite your changes. Always override in a child theme.

4. Forgetting to include The Loop in custom templates — Some templates (like front-page.php) display static content without The Loop. Others (like category.php) need have_posts() and the_post() to display posts.

5. Using the same template for every category — If you want different layouts per category, create separate files (category-news.php, category-opinion.php). A single category.php cannot provide different layouts without complex conditionals.

Practice Questions

1. What is the order of template files WordPress checks when displaying a single post with post type "book"?

2. You want a different layout for the "WordPress" category. What template file should you create, and what fallback templates will WordPress try if it does not exist?

3. How does the template hierarchy differ between front-page.php and page.php? When does WordPress use each one?

Challenge: Create a theme (or use a child theme) and implement the following: (1) front-page.php — A custom homepage with a grid of featured posts, (2) category-news.php — Full-width layout for the "News" category, (3) category-reviews.php — Layout with sidebar for "Reviews" category, (4) single.php — Post template with author bio box below content, (5) 404.php — Custom 404 page with search form and recent posts, (6) author.php — Author archive showing author avatar, bio, and post list. Verify each template loads correctly by browsing the corresponding pages.

FAQ

Mini Project

Build a complete template set for a magazine-style site:

1. Create a child theme (or use an existing one).
2. Implement the following template files:
   • front-page.php — Featured post (sticky), three-column grid of recent posts, newsletter signup section
   • single.php — Post with featured image, title, meta, content, author bio, related posts section
   • page.php — Page with title, content, and sidebar
   • category.php — Archive with category title, description, post grid. In category-editorial.php, use a full-width layout with larger featured images.
   • tag.php — Similar to category but smaller layout
   • author.php — Author archive with avatar, name, bio, post count, and list of posts
   • search.php — Search results page with query highlight, result count, search form
   • 404.php — Custom 404 with illustration (CSS), search form, popular posts, category links
3. Use get_template_part() to share common patterns across templates (content-post.php, content-none.php, content-search.php).
4. Verify each template by visiting the corresponding page type. Use Query Monitor or the debug comment method to confirm the correct template loads.

What's Next

With a deep understanding of the template hierarchy, refine your designs with CSS customization techniques. Learn to enqueue styles properly, use WordPress body classes, and follow best practices for maintainable theme styling.