We Break Down the WordPress Template Hierarchy

Anna Fitzgerald
Anna Fitzgerald

Published:

Template files are modular and reusable files that make up WordPress themes. Containing a combination of HTML, PHP code, and template tags, these PHP files are used to generate the layout and design of different parts of your WordPress website. For example, the header.php template is used to create a header and the footer.php template is used to create a footer.

Theme developer learning about WordPress template hierarchy

While some template files — like the header and footer templates — are used on all web pages, others are used only on individual pages.

To determine which template file (or files) to use on specific pages, WordPress uses a template hierarchy. Understanding this hierarchy will help you decide which template files need to be edited when customizing a WordPress theme, or which files you need when building a theme.

Let’s take a closer look at what the WordPress template hierarchy is and what it’s based on.

Grow Your Business With HubSpot's Tools for WordPress Websites

Here’s a visual representation of the hierarchy:

WordPress template hierarchy visual diagram

Image Source

When a visitor requests a particular web page, like an individual category page, WordPress will first try to find the template file with the exact matching name. If it can’t, it will skip to the next file in the hierarchy. It will keep doing so until it cannot find any matching template file. Then, it’ll fall back on the theme’s main template file: the index.php file.

Below let’s take a closer look at what the WordPress template hierarchy is based on.

When a user visits a specific page of your website, they use a link containing a query string. A query string is the sequence of codes that comes after the question mark of a link, and usually contains multiple parameters separated by ampersands. Here’s an example of a query string below:

Query string annotated in URL

WordPress uses this query string to determine what type of content is being requested — for example, is it a category page or author page being requested? Then, it searches the template hierarchy for a matching template file. Once the matching template file is found, the server will parse the PHP in the template and return HTML to the visitor.

But what if the template file doesn’t exist in the theme’s directory? Technically, a theme only needs an index.php template. While most themes are made up of multiple templates in order to display different types of content, that doesn’t mean themes will have a specific template file for every author, category, or tag page. In that case, WordPress will try to find the closest match to generate the content the visitor requested.

Let’s look at a specific example below.

Example of WordPress Template Hierarchy

Say, a visitor on your website is perusing your blog. They find a blog post they like and want to read more by the author so they click on their hyperlinked author name. In that case, WordPress will first look for the template file named author-{name}.php in the current theme’s directory. If no such file exists, then it will look for the template file with the author’s ID number, which would be named author-{id}.php.

If that file is missing, it will look for a generic author template file named author.php. This is the default template used to display all author archive pages. If that file is missing, it will look for a generic archive template file named archive.php. This is the default template used to display all archive pages, including category, tag, custom taxonomy, custom post type, and date-based archives. If it still comes up with nothing, then it will default to the index.php template.

In short, here’s the template hierarchy for author pages:

  1. author-{name}.php
  2. author-{id}.php
  3. author.php
  4. archive.php
  5. index.php

Not every query type has such a detailed hierarchy. Some — like the homepage — only have two template files that WordPress will potentially use. WordPress will first try to find the home.php template file. If it can’t, WordPress will use the index.php template file.

Let’s detail the template hierarchy for each query type below.

A Breakdown of the WordPress Template Hierarchy by Query Type

WordPress websites are made up of several query types — or types of content — including front pages, single posts, single pages, category and tag archive pages, author archive pages, search pages, and more. Each query type has a unique order in which template files are called by WordPress. Let’s outline those in the table below.

Note: the table follows the order laid out in the screenshot above.

Query Type Template Hierarchy
Author Display Page
1. author-{name}.php
2. author-{id}.php
3. author.php
4. archive.php
5. index.php
Category Page
1. category-{slug}.php
2. category-{id}.php
3. category.php
4. archive.php
5. index.php
Custom Taxonomy Page
1. taxonomy-{taxonomy}-{term}.php
2. taxonomy-{taxonomy}.php
3. taxonomy.php
4. archive.php
5. index.php
Date-based Archive Page
1. date.php
2. archive.php
3. index.php
Tag Page
1. tag-{slug}.php
2. tag-{id}.php
3. tag.php
4. archive.php
5. index.php
Single Post
1. single-{post-type}-{slug}.php
2. single-{post-type}.php
3. single.php
4. singular.php
5. index.php
Custom Post Types
1. archive-{post_type}.php
2. archive.php
3. index.php
Attachment
1. {MIME-type}.php
2. attachment.php
3. single-attachment-{slug}.php
4. single-attachment.php
5. single.php
6. singular.php
7. index.php
Single Page
1. custom template file assigned to the page
2. page-{slug}.php
3. page-{id}.php
4. page.php
5. singular.php
6. index.php
Site Front Page
1. front-page.php
2. home.php
3. page.php
4. index.php
Blog Posts Index Page (or Home Page)
1. home.php
2. index.php
Error 404 Page
1.404.php
2.index.php
Search Results Page
1.search.php
2.index.php
Embeds
1. embed-{post-type}-{post_format}.php
2. embed-{post-type}.php
3. embed.php
4. wp-includes/theme-compat/embed.php

Use HubSpot tools on your WordPress website and connect the two platforms  without dealing with code. Click here to learn more.

Related Articles

Capture, organize, and engage web visitors with free forms, live chat, CRM, analytics, and more.

DOWNLOAD THE FREE PLUGIN