Template Hierarchy – Developing WordPress Themes Part 5

Template Hierarchy – Developing WordPress Themes Part 5

As discussed, template files are standard and reusable files, which are used to create web pages on your WordPress site. Some form files (such as the form header and footer) are used on all pages of your site, while others are used only under specific conditions.

This article explains how WordPress determines which template file(s) to use on individual pages. If you want to customize a pre-existing WordPress theme, it will help you decide which template file to edit.


WordPress uses the query string to specify which template or set of Theme to use to display the page. The query string is the information in the link for each part of your website. It comes after the initial question mark and may contain a number of parameters separated by ampersands.

  • Simply put, WordPress searches through the template hierarchy until it finds a matching template file. To specify the template file to use, WordPress:
  • matching each query string with a query type to select the desired page (for example, a search page, a category page, etc.);
    Selects the template in the order specified by the template hierarchy;
    Finds form files with given names in the current template directory and uses the first matching form file as defined by the hierarchy.

Except for the core index.php template file , you can choose whether or not to execute a specific template file.

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

examples # examples

If your blog is at http://example.com/blog/ and the visitor clicks a link to a taxonomy page like http://example.com/blog/category/your-cat/ , then WordPress looks for a sample file in the current template directory that matches Category ID to create the correct page. More specifically, WordPress follows this procedure:

  • Finds a template file in the current template directory that matches the class slug. If the slug category is “unicorns”, then WordPress looks for a template file named category-unicorns.php .
  • If category-unicorns.php is missing and category ID is 4, WordPress looks for a template file named category-4.php .
  • If category-4.php is missing, then WordPress will look for a generic category template file, category.php.
  • If category.php is not present , WordPress will search for a generic archive template, archive.php.
  • If the archive.php file is also missing, then WordPress will return to the main theme template file, index.php.

Visual overview # Visual overview
The following diagram shows the template files called to create a WordPress page based on the WordPress theme hierarchy.

Screenshot 2019 01 23 00.20.04
WordPress template hierarchy

Template hierarchy in detail # Template hierarchy in detail

While the template hierarchy is easy to understand as a schema, the following sections describe the order in which template files are called by WordPress for a number of query types.

Note: Under each title there is a set of options, only one can be used to display the file you want on your site.. We have given all the options, just to show how calling template files with WordPress.

Show home page # Show home page

  1. home.php
  2. index.php

front page display #

  1. front-page.php 
  2. home.php
  3. page.php 
  4. index.php

View the privacy policy page #

  1. privacy-policy.php.
  2. page-{slug}.php
  3. page-{id}.php
  4. page.php
  5. singular.php
  6. index.php

default article #

  1. single-{post-type}-{slug}.php
  2. single-{post-type}.php
  3. single.php 
  4. singular.php
  5. index.php

pages #

  1. custom template file
  2. page-{slug}.php 
  3. page-{id}.php
  4. page.php
  5. singular.php
  6. index.php

Categories #

  1. category-{slug}.php
  2. category-{id}.php
  3. category.php
  4. archive.php
  5. index.php

hashtags #

  1. tag-{slug}.php
  2. tag-{id}.php 
  3. tag.php
  4. archive.php
  5. index.php

# custom categories

  1. taxonomy-{taxonomy}-{term}.php
  2. taxonomy-{taxonomy}.php
  3. taxonomy.php
  4. archive.php
  5. index.php

# custom post types

  1. archive-{post_type}.php 
  2. archive.php
  3. index.php

view author #

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


  1. date.php
  2. archive.php
  3. index.php

search result #

  1. search.php
  2. index.php

404 Not Found) #

  1. 404.php
  2. index.php

Attached #

  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

embed #

  1. embed-{post-type}-{post_format}.php 
  2. embed-{post-type}.php 
  3. embed.php