Learn how WordPress selects the correct template file to display your homepage, posts, pages, categories, search results, and other website content.
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.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.
WordPress follows this general process:
| 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. |
A single post template is used when a visitor opens an individual blog post. WordPress looks for increasingly general templates.
For a standard blog post, WordPress checks:
single-post-slug.php — where applicable, a template for a particular post.single-post.phpsingle.phpsingular.phpindex.phpWordPress uses the first applicable template that exists. For custom post types, filenames can include the post type.
WordPress pages are different from blog posts. For example, About Us, Contact Us, and Services are usually pages.
page-about-us.phppage-42.php — if the page ID is 42.page.phpsingular.phpindex.php
The slug-specific filename is an example. Replace
about-us with your page's actual slug.
Category archives display posts belonging to a particular category, such as PHP Tutorials or WordPress Tutorials.
wordpress,
WordPress generally checks:
category-wordpress.phpcategory-5.php — if the category ID is 5.category.phparchive.phpindex.phpThe slug-specific and ID-specific files are optional. The ID shown here is only an example.
When visitors search your website, WordPress checks:
search.phpindex.php
Use search.php to customize the
appearance of search results in a classic theme.
When a requested page cannot be found, WordPress checks:
404.phpindex.php
Use 404.php to display a helpful
message and links to other pages.
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.
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.
<?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(); ?>
templates/ directory, along with
theme.json for settings and styles.
You can create a custom page template to give a specific page a different layout.
page-services.php.
<?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(); ?>
services.
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.
| 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. |
index.php file if it is a classic theme.page.php and single.php, if present.page-services.php file in a child theme.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.Choose the correct answer for each question.