Breaking Down the WordPress Template Hierarchy

Anna Fitzgerald
Anna Fitzgerald

Published:

Template files are modular and reusable files that make up WordPress themes. WordPress uses a template hierarchy to determine which template file (or files) to use on specific pages. 

Theme developer learning about WordPress template hierarchy

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

Grow Your Business With HubSpot's Tools for WordPress Websites

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.

Use the following jump links to navigate the article or just keep scrolling:

Here's a helpful video primer on the WordPress Template Hierarchy.

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 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 finds no 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:

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 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.

Example of WordPress Template Hierarchy

A visitor on your website finds a blog post they like and wants 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, 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 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.

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

As you can see, the template hierarchy varies depending on what kind of query the user requests. Use this table as a reference when customizing a template or creating a WordPress Theme.

Using the WordPress Template Hierarchy

The WordPress template hierarchy determines which template file will be used to generate a web page based on the requested content and the availability of corresponding template files in the theme's directory. By following the template hierarchy, you can easily locate and edit the necessary template files for your specific needs.

Whether you are a WordPress developer or a website owner looking to customize your theme, knowing the template hierarchy will help you navigate and make the most out of WordPress's powerful templating system.

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

CMS Hub is flexible for marketers, powerful for developers, and gives customers a personalized, secure experience

START FREE OR GET A DEMO