To freely change the design of a WordPress site, you edit the template files within the theme. However, which template is used on which page is not fixed — WordPress automatically selects it based on conditions. This mechanism is called the “template hierarchy.” By understanding the hierarchy, you can change the design only for specific pages and make future maintenance easier. Here, with reference to the official WordPress documentation, we’ll explain the template hierarchy and the main template files in a beginner-friendly way.

What is the template hierarchy?

When a web browser requests a page from a WordPress site, WordPress first checks the query string to determine the type of page being accessed — for example, a “search page,” “category page,” or a “single post page.” Next, it looks through the theme’s files in the order defined by the template hierarchy and applies the first matching template. If no specific template is found, it falls back to more general ones, and finally to index.php. If you’re using a child theme, its files take priority over the parent theme.

Key points:

  • WordPress searches from the most specific file first. If a template file includes a slug or ID in its name, that takes top priority.
  • If no match is found, it moves on to the next candidate, and eventually falls back to index.php.
  • For block themes, the file extension is .html, but the hierarchy concept remains the same.

Common query types and template priority

The official documentation covers many cases. Here, we summarize the typical page types and the order in which files are used. More specific files take priority, and if none exist, more general templates are used lower in the list.

Template hierarchy tree diagram

Homepage and Front Page

The site’s front page (blog index or static page) mainly uses the following templates:

  • front-page.php – Always takes priority for the front page, whether set to “latest posts” or a “static page.”
  • home.php – Used for the blog posts index if front-page.php is absent. Also applies when blog posts are assigned to another page.
  • page.php – Used if the front page is set to a static page and neither front-page.php nor home.php exists.
  • index.php – The final fallback.

Posts (single)

Individual posts are loaded in the following order:

  1. single-{post-type}-{slug}.php – Since 4.4, templates with post type and slug take highest priority.
  2. single-{post-type}.php – For custom post type single posts.
  3. single.php – General post template.
  4. singular.php – Generic template for both posts and pages.
  5. index.php – Final fallback.

Pages (page)

The priority for static pages (page post type) is:

  1. Custom page template – Assigned from the admin panel.
  2. page-{slug}.php – Template for the specific slug.
  3. page-{id}.php – Template for the specific page ID.
  4. page.php → singular.php → index.php – Falls back to general templates.

Archive pages

Category, tag, and other archive pages load templates in the following order:

Category

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

Tag

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

Custom taxonomy

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

Custom post type archive

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

Author & Date archives

  • Author: author-{nicename}.php → author-{id}.php → author.php → archive.php → index.php
  • Date: date.php → archive.php → index.php

Search, 404, Attachments, Embeds

  • Search results: search.php → index.php
  • 404 page: 404.php → index.php
  • Attachment: MIME-type specific → attachment.php → single-attachment-{slug}.php → single-attachment.php → single.php → singular.php → index.php
  • Embed: embed-{post-type}-{post_format}.php → embed-{post-type}.php → embed.php → WordPress internal template

Non-ASCII characters & filters

Since WordPress 4.7, when template names include non-ASCII characters (like Japanese), both encoded and unencoded file names can be used. You can also add custom templates to the hierarchy through filters. For example, the author_template filter can be used to prioritize author-editor.php depending on the author’s role.

Frequently used template files

Although WordPress themes have many templates, the basic ones used most often are limited. The table below, based on the official “Common WordPress template files,” summarizes representative templates and their purposes.

Template FilePurpose (short description)
index.phpMost generic template. Final fallback for all templates.
style.cssTheme stylesheet and theme information.
front-page.phpAlways used for the site’s front page.
home.phpDisplays the blog posts index (latest posts).
singular.phpUsed for both posts and pages if single.php or page.php don’t exist.
single.phpDisplays a single post.
single-{post_type}.phpDisplays a custom post type single post.
archive-{post_type}.phpDisplays a custom post type archive.
page.phpDisplays static pages.
page-{slug}.phpDisplays a specific slug’s page.
category.phpDisplays category archives.
tag.phpDisplays tag archives.
taxonomy.phpDisplays custom taxonomies.
author.phpDisplays author archives.
date.phpDisplays date archives.
archive.phpDisplays general archives.
search.phpDisplays search results.
attachment.phpDisplays an attachment.
image.phpDisplays an image attachment.
404.phpDisplays a 404 (Not Found) page.
comments.phpComment template.

Template parts

Template parts are used to manage parts of a page instead of the whole. Common examples include header.php (header), footer.php (footer), and sidebar.php (sidebar). These are included in templates with tags like get_header() and get_footer(). The official documentation also provides examples of functions such as get_header() and get_template_part(), which are useful references.

Tips for customizing with the template hierarchy

  1. Create specific templates for specific pages
    For example, creating category-news.php allows you to apply a different design only to the “news” category archive.
  2. If no template is found, index.php is displayed
    The site won’t go blank even if you forget to customize, but since the fallback is a generic template, the design may not be consistent.
  3. Use child themes
    Editing a theme directly risks being overwritten on updates. Adding templates in a child theme is safer since they take priority over parent theme files.
  4. Manage common parts with template parts
    Extract headers and footers into separate files so they can be called from multiple templates. When changes are needed, editing the part once updates it everywhere.
  5. Extend the hierarchy with filters
    If you want to change template priority based on conditions, use filters. For example, with the author_template filter you can switch templates based on the author’s role.

Summary

The template hierarchy is WordPress’s rule for “which template file to use.” It searches for the most appropriate template based on the query type, and falls back to more general ones if no match is found. By understanding the role of frequently used template files and parts, and creating files with the hierarchy order in mind, you can build stable themes with designs that work as intended.

References