WordPress Tutorial
Lesson 39 of 50 (78%)
78% Complete

WordPress Template Hierarchy

Learn how WordPress selects the correct template file to display your homepage, posts, pages, categories, search results, and other website content.

Learning Objective: Understand the WordPress template hierarchy, learn important template filenames, and discover how to create custom templates in a WordPress theme.

1. What Is Template Hierarchy?

The WordPress Template Hierarchy is the system WordPress uses to decide which template file should display a particular page on your website.

When a visitor opens a page, WordPress checks the available template files in a defined order. It uses the most specific matching template that exists. If no matching template is found, WordPress falls back to a more general template.

Example
Suppose your website contains a page with the URL: example.com/about-us/

WordPress may use page-about-us.php to display this page if that file exists in the active classic theme. Otherwise, it checks other suitable templates.

2. How Template Hierarchy Works

WordPress follows this general process:

Template Selection Process
  1. A visitor requests a URL.
  2. WordPress identifies the type of content requested.
  3. WordPress checks the relevant template filenames.
  4. It selects the most specific available template.
  5. If no specific template exists, it uses a fallback.
  6. The selected template displays the content.

3. Important WordPress Template Files

Template File Purpose
front-page.php Displays the site's front page when this template is available.
home.php Displays the blog posts index.
index.php The main fallback template in a classic theme.
single.php Displays individual posts when a more specific template is not available.
page.php Displays individual pages.
archive.php Displays archive pages.
category.php Displays category archive pages.
tag.php Displays tag archive pages.
author.php Displays author archive pages.
search.php Displays search results.
404.php Displays the not-found page.
comments.php Provides the theme's comments display template; it is not a main page hierarchy template.

4. Single Post Template Hierarchy

A single post template is used when a visitor opens an individual blog post. WordPress looks for increasingly general templates.

Example: Displaying a Blog Post

For a standard blog post, WordPress checks:

  1. single-post-slug.php — where applicable, a template for a particular post.
  2. single-post.php
  3. single.php
  4. singular.php
  5. index.php

WordPress uses the first applicable template that exists. For custom post types, filenames can include the post type.

5. Page Template Hierarchy

WordPress pages are different from blog posts. For example, About Us, Contact Us, and Services are usually pages.

Example: About Us Page
WordPress generally checks the following classic-theme options:
  1. An assigned custom page template, if selected.
  2. page-about-us.php
  3. page-42.php — if the page ID is 42.
  4. page.php
  5. singular.php
  6. index.php

The slug-specific filename is an example. Replace about-us with your page's actual slug.

6. Category Template Hierarchy

Category archives display posts belonging to a particular category, such as PHP Tutorials or WordPress Tutorials.

Example: WordPress Category
For a category with the slug wordpress, WordPress generally checks:
  1. category-wordpress.php
  2. category-5.php — if the category ID is 5.
  3. category.php
  4. archive.php
  5. index.php

The slug-specific and ID-specific files are optional. The ID shown here is only an example.

7. Search and 404 Templates

Search Results

When visitors search your website, WordPress checks:

  1. search.php
  2. index.php

Use search.php to customize the appearance of search results in a classic theme.

404 Not Found

When a requested page cannot be found, WordPress checks:

  1. 404.php
  2. index.php

Use 404.php to display a helpful message and links to other pages.

8. Archive Template Hierarchy

An archive page displays a collection of posts. Archives can represent categories, tags, authors, dates, or custom post types.

Archive Type Specific Template General Fallback
Tag tag-news.php tag.php, archive.php, index.php
Author author-john.php author.php, archive.php, index.php
Date date.php archive.php, index.php
Custom Post Type archive-book.php archive.php, index.php

Note: These are simplified examples. The exact hierarchy depends on the requested content type and the templates supported by the theme.

9. The Importance of index.php

In a classic WordPress theme, index.php is the final fallback for many front-end requests. If WordPress cannot find a more specific applicable template, it can use this file.

Example: index.php
<?php get_header(); ?>

<main class="container py-4">
    <h1>Website Content</h1>

    <?php if ( have_posts() ) : ?>
        <?php while ( have_posts() ) : the_post(); ?>

            <h2>
                <a href="<?php the_permalink(); ?>">
                    <?php the_title(); ?>
                </a>
            </h2>

            <?php the_excerpt(); ?>

        <?php endwhile; ?>
    <?php else : ?>
        <p>No content found.</p>
    <?php endif; ?>
</main>

<?php get_footer(); ?>
Important: This example is for a classic PHP theme. Block themes commonly use HTML templates and template parts inside a templates/ directory, along with theme.json for settings and styles.

10. How to Create a Custom Page Template

You can create a custom page template to give a specific page a different layout.

Step 1: Create a PHP File
Inside your classic theme or child theme, create a file named page-services.php.
Step 2: Add the Template Code
<?php
/**
 * Template for the Services page.
 */

get_header();
?>

<main class="container py-5">
    <h1>Our Services</h1>

    <p>Welcome to our services page.</p>

    <div class="row g-3">
        <div class="col-md-4">
            <div class="card p-3 h-100">
                <h2>Web Design</h2>
                <p>Professional website design services.</p>
            </div>
        </div>

        <div class="col-md-4">
            <div class="card p-3 h-100">
                <h2>Development</h2>
                <p>Modern website development services.</p>
            </div>
        </div>

        <div class="col-md-4">
            <div class="card p-3 h-100">
                <h2>Support</h2>
                <p>Website maintenance and support.</p>
            </div>
        </div>
    </div>
</main>

<?php get_footer(); ?>
Step 3: Open the Page
  1. Open WordPress Admin.
  2. Go to Pages and create or edit a page named Services.
  3. Set its slug to services.
  4. Publish the page and visit its URL.

The filename page-services.php is automatically matched to the page slug in a classic theme. You do not need to select it from a template dropdown.

11. Classic Themes vs Block Themes

Classic Themes Block Themes
Primarily use PHP template files. Primarily use HTML block templates.
Examples: single.php, page.php. Examples: templates/single.html, templates/page.html.
Often use get_header() and get_footer(). Use block markup and template parts.
Can use the PHP template hierarchy. Use block-theme template resolution and HTML templates.

12. Best Practices

Tips for Developers
  • Use specific templates when a page needs a unique design.
  • Follow WordPress template filename conventions.
  • Use a child theme when modifying an existing theme.
  • Never modify WordPress core files to change a layout.
  • Test template changes on a development or staging site.
  • Use WordPress template tags and escaping functions appropriately.
  • Understand whether your active theme is a classic theme or a block theme.

13. Practical Assignment

Your Task
  1. Identify whether your active theme is a classic theme or block theme.
  2. Find the theme's index.php file if it is a classic theme.
  3. Find page.php and single.php, if present.
  4. Create a page-services.php file in a child theme.
  5. Create a Services page and check the layout in the browser.
  6. Explain what WordPress does if a specific template file is missing.

14. Lesson Summary

  • Template hierarchy determines which template WordPress uses.
  • page.php is commonly used for pages.
  • single.php is commonly used for individual posts.
  • archive.php handles many types of archives.
  • search.php displays search results.
  • 404.php displays a not-found page.
  • index.php is the final fallback in classic themes.
  • Block themes use HTML templates and template parts.

Lesson 39 Quiz: Template Hierarchy

Choose the correct answer for each question.

1. What is the WordPress template hierarchy?

2. Which file is the final fallback template in a classic WordPress theme?

3. Which file commonly displays individual blog posts in a classic theme?