The WordPress Template Hierarchy

You may have noticed that different WordPress themes contain different page templates. Complex WordPress themes may have dozens and dozens of theme templates, while lighter themes might only have a few.

The only two files you need for a WordPress theme are style.css and index.php. A basic theme like that will use the index.php to display the home page, blog posts, pages, archives, and more.

Such a simple WordPress theme can exist because WordPress has a template hierarchy. For each type of page, WordPress searches for a specific template. If that template does not exist, it looks for another, and then another.

Take the single post page, for example. This is the page that displays blog posts on a WordPress website.

Most WordPress users know that the single.php theme template powers this page. However, what you may not know is that WordPress first looks for the single-{post_type}.php file. If the post in question was a quote, WordPress would initially look for a template entitled single-quote.php. Likewise, with a gallery, it would search for a template entitled single-gallery.php.

If no single-{post_type}.php template file exists, WordPress will then search for the single.php template. And if no single.php template exists, WordPress will use index.php.

The template hierarchy for the single post page is thus:

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

The template hierarchy for pages is a little longer, though it follows the same principle.

As you know, WordPress allows you to choose a specific page template for your pages. This is a great feature that lets style certain parts of your website differently. It can also be used to add functionality to specific pages.

The first template file that WordPress checks for is therefore the custom template that has been assigned to the page. For example, if you have assigned a news template for your page, it would look for that template firsthand.

If no page template has been assigned, WordPress looks for a template that matches the page slug (page-{slug}.php). For example, if WordPress loads your about page, it would look for the template page-about.php (this of course assumes that your page slug is also named about).

If no template matches the page slug, WordPress searches for a page template that matches the ID of your page. So if the page ID of your about page was 1, WordPress would search for a template entitled page-1.php.

If that template does not exist, WordPress searches for the page.php template. And in the event that the theme does not have a page.php template, WordPress will use the index.php template.

The template hierarchy for pages is thus:

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

The diagram below, courtesy of WordPress.org, illustrates the template hierarchy of WordPress. As you can see, the index.php template file is always used when all other appropriate templates cannot be located.

(Click on the image below for the full size image)

Once you begin to understand the principle of how template hierarchy works, you will be able to use it to your advantage and customize your website accordingly. For example, you can use it style categories differently or to create a different author template for each member of staff. It offers a lot of customization.

To find out more about how the WordPress template hierarchy works, please visit WordPress.org.

Thanks,
Kevin