Home > Help Center > Applications > WordPress > WordPress Template Hierarchy

WordPress Template Hierarchy

WordPress template hierarchy is the way WordPress determines what file in the theme will be used to generate the complete HTML for a given page of a WordPress website by following a strict file naming rules.

How WordPress determines which template files to use on individual pages? WordPress themes are made up of template files. These are PHP files that contain a mixture of HTML, Template Tags, and PHP code.

When you are building your theme, you will use template files to create different parts of your website. For example, you would use the header.php template to create a header, or the comments.php template to include comments.

When someone visits a page on your website, WordPress loads a template based on the request. The type of content that is displayed in by the template file is determined by the Post Type associated with the template file.

The Template Hierarchy describes which template file WordPress will load based on the type of request and whether the template exists in the theme. The server then parses the PHP in the template and returns HTML to the visitor.

The most critical template file is index.php, which is the catch-all template if a more-specific template can not be found in the template hierarchy. Although a theme only needs a index.php template, typically themes include numerous templates to display different content types and contexts.

WordPress searches down through the template hierarchy until it finds a matching template file. To determine which template file to use, WordPress:

  • Matches every query string to a query type to decide which page is being requested (for example, a search page, a category page, etc);
  • Selects the template in the order determined by the template hierarchy;
  • Looks for template files with specific names in the current theme's directory and uses the first matching template file as specified by the hierarchy.

With the exception of the basic index.php template file, you can choose whether you want to implement a particular template file or not.

If WordPress cannot find a template file with a matching name, it will skip to the next file in the hierarchy. If WordPress cannot find any matching template file, the theme's index.php file will be used.

Template Hierarchy Example

To show template hierarchy in action we are going to create: - New category Hierarchy (hierarchy) - New post WordPress Hierarchy Example and assign it to hierarchy category - New files in our theme twentyseventeen: category-hierarchy.php category-33.php category.php

We will copy the entire content of archive.php file and we will paste it in each of the new files.

At the top of each file we are going to put its file name within H2 tags <h2>category-hierarchy.php</h2>

Also we have installed a plugin Show Current Template which shows what template file WordPress uses to display certain webpage. To use the plugin you must be logged while browsing the site and make sure the box in front of Show Toolbar when viewing site label on the Profile screen (to enter it click Users > Your Profile) is checked.

Here are our new files within the twentyseventeen theme folder:

wordpress template hierarchy

To start our example on template hierarchy we are loading our site http://hostpulse-demo.net and click on the category Hierarchy link http://hostpulse-demo.net/category/hierarchy/:

wordpress template hierarchy

The first choice of WordPress to load a category archive is category-hierarchy.php. Now let's rename this file to _category-hierarchy.php and to refresh the same page:

wordpress template hierarchy

Now WordPress uses the template file category-33.php. But how we got this number 33?

Go back to Dashboard > Posts > Categories, hover over Hierarchy category and click Edit or Quick edit links:

wordpress template hierarchy

Click within the address bar and you are going to notice tag_ID=33 part of the URL. Following WordPress naming conventions we can create template files using contenttype-$ID.php syntax.

For example we can create template file single-123.php and if there is post with tag_ID=123 this file will be used by WordPress to display this particular post ignoring the existence of single.php file.

To continue our example let's rename category-33.php to _category-33.php and to load http://hostpulse-demo.net/category/hierarchy/ again:

wordpress template hierarchy

The next file used by WordPress is category.php. Let's rename it to _category.php and to refresh the page in the browser:

wordpress template hierarchy

This time WordPress used archive.php template. Let's rename it to _archive.php and refresh the page again:

wordpress template hierarchy

WordPress uses the last available option index.php. We cannot rename or delete index.php file because WordPress will stop working:

wordpress template hierarchy

If a visitor clicks on a link to a category page such as http://hostpulse-demo.net/category/hierarchy/, WordPress looks for a template file in the current theme's directory that matches the request to generate the correct page.

More specifically, WordPress follows this procedure:

  • First it looks for a template file in the current theme's directory that matches the category's slug.
  • If the category slug is hierarchy, then WordPress looks for a template file named category-hierarchy.php.
  • If category-hierarchy.php is missing and the category's ID is 33, WordPress looks for a template file named category-33.php.
  • If category-33.php is missing, WordPress will look for a generic category template file, category.php.
  • If category.php does not exist, WordPress will look for a generic archive template, archive.php.
  • If archive.php is also missing, WordPress will fall back to the main theme template file, index.php.

Template hierarchy visual graphics

The following diagram shows which template files are called to generate a WordPress page based on the WordPress template hierarchy:

wordpress template hierarchy

The same diagram is available online - by clicking on any link on the diagram you can find additional information from codex.wordpress.org.


Knowing how WordPress works and how to properly build the file structure of a WordPress site is one of the most important initial steps in creating WordPress themes.

Reference: developer.wordpress.org

#website #content

Still not finding what you're looking for?

Contact our support team with any additional questions or concerns.

Contact support