The WordPress Template Hierarchy

Tahir Taous

WordPress themes allow you to change the design of your website, providing control over the look and feel. They are essentially collections of different template files that work together and produce the overall design of your website.

Before you dive deeper into WordPress themes, it is important that you have an understanding of how WordPress operates and how the different pages of your website are created. WordPress interacts with a database to store your content. That means whenever you create a new post or page, the content of your post or page lives in a database and it’s only displayed using templates when the visitor asks for that particular content.

A WordPress theme is a collection of templates (CSS and PHP files) that WordPress uses to display the database content. WordPress will look for files in a theme to use to render the current page in a specific order. This is called a ‘template hierarchy’, that is used to create and extend WordPress themes.

WordPress themes decide how your content should be displayed on your website. A template in WordPress is a single file that determines what a specific page or set of pages look like on the front end of your website. When you change your theme, you are changing the way the content is displayed without changing the content itself.

WordPress themes use different templates files to generate a complete web page. For example, when you access a WordPress website, you can actually see multiple different template files combined together to create one complete page.

For instance, if you will look at an index page, like the front page of a blog, you will usually see a header created by the header.php template, content created by index.php, sidebar created by sidebar.php and the footer created by footer.php


A Basic WordPress Theme

However, if you access a single page, you will still see the same header, same sidebar and same footer but the content would be created by single.php instead. The question is how do you know which of these template files kick in and at what point? That’s where the WordPress template hierarchy comes in.

The WordPress template hierarchy determines in what order your template files are loaded within your WordPress theme. WordPress searches for these files, to determine how to load your site.

If you open the ‘Twenty Fifteen’ (one of the default WordPress themes) theme folder, there are more than 15 templates files. These include template files for 404, archive, author-bio, comments and content-link just to name a few. WordPress will use the Query String information contained within each link on your website to decide which template or set of templates will be used to display the page.

WordPress decides what type of page (search page, category page or home page for example) is being requested and then chooses the appropriate template suggested by the WordPress Template hierarchy to generate the content.

Naming Convention

WordPress has a special and strict naming convention associated with theme files, so all themes share a fairly commonly named set of files in the back end. For example, to easily manage your content you can create header.php and footer.php files. These template files must be named header.php and footer.php.

WordPress looks for template files with specific names in the current theme’s directory to determine which template to use, most commonly the first matching template file is used. If WordPress cannot find a template file with a matching name, it skips down to the next file name in the hierarchy. If WordPress fails to find any matching template file, it will use index.php (the theme’s home page template file).

So when you are editing template files what you have to think about is what type of content this is, then edit the appropriate template file for that type of content. The same applies to when you’re creating WordPress themes from scratch.

Minimum Theme Requirements

The only files that are required for a WordPress theme to work are index.php and style.css. The index.php is the main and only file that will process every WordPress query, as well as the structure of the site.

The minimum files required for a WordPress theme to work and to be visible in the WordPress dashboard for activation are index.php and style.css.

If index.php or style.css are missing, you will see following error.

The following themes are installed but are incomplete. Themes must have a style-sheet and a template.

  • style.css (required)

  • index.php (required)

  • functions.php (optional)

  • screenshot.png (optional)

This separation greatly increases efficiency. Combining everything into one big single file index.php might technically work, but it wouldn’t be pretty, and would cause endless issues down the line. Also editing a theme would be a nightmare!

Here is the list of the theme files recognized by WordPress.

  • style.css

  • rtl.css

  • index.php

  • comments.php

  • front-page.php

  • single.php

  • page.php

  • author.php

  • archive.php

There are many other files as well, you can view the template files list for more details.

Twenty Fifteen Template Hierarchy Example

Suppose you have activated the Twenty Fifteen theme and a user visits the page First, WordPress will search for the template labeled author-tahir.php but author-tahir.php is not available. WordPress will then look for author.php, if it also does not exist, it will look for archive.php. This file is available in Twenty Fifteen theme. If you delete or rename archive.php then WordPress will use index.php to render the page.

Each time a user visits your website, WordPress moves up the template hierarchy until it finds a template file that matches. This has everything to do with how these files are named.

The ‘What The File’ Plugin

To find out what file and template WordPress is using to display page content you are currently viewing, you can use the very handy What The File Plugin. This is a free plugin developed by Barry Kooij.

This plugin adds an option to your toolbar showing what file and templates are being used. I installed the ‘What The File Plugin’ for testing purposes on my local server and found it worked great.

To test which files WordPress uses if a specific file isn’t available, I renamed two files (in the Twenty Fifteen Theme). In the screenshot below you can see which files WordPress uses to display content.

The What The File Plugin

You can see the Twenty Fifteen theme uses the content-search.php file to display search results. If you delete or rename content-search.php, WordPress will use content.php to display search results instead.

The ‘What The File’ plugin also allows you to click the file name directly to edit it through the theme editor. This plugin requires WordPress 3.1 or higher, it worked fine with WordPress 4.1 as well.

Useful Resources

If you’re interested in learning more about the WordPress template hierarchy and theme development in general, I’d recommend the following resources: