1. Code
  2. Theme Development

The WordPress Theme Files Execution Hierarchy

Scroll to top
Read Time: 4 min

This article will show the WordPress theme file execution hierarchy. In short, we'll look at which files get served up when you load a page in WordPress. You might already know that detail post is served by single.php and detail page is served by page.php, but WordPress will search for different files depending on a variety of factors, so we'll be looking at how this works!

First thing we should establish is this: without index.php and style.css your theme is no longer a valid WordPress theme... so it stands to reason that if all you have is those two files, each page will you try to load will be served up by index.php. Take a quick peek at this "cheatsheet" to see what I'm referring to:

Notice that the flow for each page types will end up with the index.php. That is the reason why index.php is required file for the WordPress theme. If we are missing any other files in WordPress theme (for instance, if there is no "search.php" file included in the theme), then index.php will be served instead.

Now let's look at some details about the execution order. I am going to show you the flow in which WordPress will search for files in your active theme folder. I hope this will be useful when you create a WordPress theme from now on:

I will go through each type of files one by one and will show the execution hierarchy for the same.

Home Page

This is the first and most important page of any website. So WordPress has provided the scope to customize the page. Let's have a look at the file hierarchy for the home page.

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

While serving the home page, WordPress will search for front-page.php. If that is not found, it will use home.php. If home.php exists, it'll use that. If not, it will simply default to using index.php.

WordPress Post Detail

  1. single-[post-type].php
  2. single.php
  3. index.php

WordPress can have as many post types as we need. So this will be easier to get different design for all/some post types. By default 'post' is the main and default post type of the WordPress.

So for example, if your custom post type is product then it will be single-product.php

To know more how to add new post types in WordPress you can refer to this link.

WordPress Page Detail

  1. [custom-template].php
  2. page-[slug].php
  3. page-[id].php
  4. page.php
  5. index.php

Just the same as with post types, we can have a different page layout using the custom page template. So WordPress first searches for the files of the selected Page template (if it exists).

If none are found, it will search for the file with the slug of the current page. Basically, if the slug is aboutus, then it will search for the file page-aboutus.php in active theme folder.

WordPress will search for the files with the ID just like searching for the files with slug.

Category Page

  1. category-[slug].php
  2. category-[id].php
  3. category.php
  4. archive.php
  5. index.php

From the above flow, you can understand that how you can have different templates used for the category page. For instance, you could have a custom page based on slug and id, and then use a default "category.php" file for the rest of your categories..

Tag Page

  1. tag-[slug].php
  2. tag-[id].php
  3. tag.php
  4. archive.php
  5. index.php

This will be same case as the category. You can have different pages for tag slug and tag id also.

Taxonomy Page

  1. taxonomy-[tax]-[term].php
  2. taxonomy-[tax].php
  3. taxonomy.php
  4. archive.php
  5. index.php

Here goes the different file hierarchy for the taxonomy Pages.

Author Page

  1. author-[author-nicname].php
  2. author-[author-id].php
  3. author.php
  4. archive.php
  5. index.php

Here you come to know that you can have different designs based on users also. Same as category and tags we can have different files based on slug and ID of the user.

Attachment Page

  1. [mime-type].php
  2. attachment.php
  3. single.php
  4. index.php

Here you can see that you can have different page layout for different types of attachment. These can be differentiate from the mime type of the attached file.

Date Page

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

For the date specific layout we can create date.php in theme folder. Then the flow goes to archive.php and then at last index.php.

Archive Page

  1. archive.php
  2. index.php

As we come downwards to the type of files, number of files are reduced in the hierarchy. So this are the basic or we can say most used files in any WordPress themes.

Search Page

  1. search.php
  2. index.php

You can customize your search result with the search.php first. If search.php is not available then index.php will be served.

404 Page

  1. 404.php
  2. index.php

In the case of page or post not found, WordPress will search for 404.php then if not found then it will serve index.php.


You can obviously use this information in a wide range of ways to load up custom templates for various pages... In many cases, even if you're using an existing theme, you can get a custom solution without modifying the existing files. You will just need to create new file and give it a new name using the information above.

Share your thoughts and any additional file which can be included above hierarchy.

Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.