The Ultimate Guide to Theme Template Files in WordPress

If you’ve ever delved under the hood of a WordPress theme, you’ll know that it contains four kinds of files: the stylesheet, the functions file, a number of template parts, and one or (most likely) more template files.

For a theme to work, it must have at least two files: the stylesheet and an index.php template file. But most themes will have more template files than that, each of which is designed to display different kinds of content.

In this post, I’ll explain which template files do what and how WordPress decides which template file to use when displaying a given page on your site.

Continue reading, or jump ahead using these links:

The Kinds of Template File

There are six kinds of template files which you can use in your themes. These are:

Template files for displaying individual posts, pages or other post types.
Template files for displaying archives, such as category archives, tag archives, date archives, author archives
The template files for the home page and /or the main blog page, front-page.php and home.php.
Template files for displaying special pages such as the 404 page.
The index.php file, which can be used to display single posts or archives in the absence of a more specific template file.
Template parts. These aren’ t really template files but they are worth mentioning as you will use them within your template files.

In a moment I’ll work through each of these in turn but first it helps to know how WordPress selects template files.

The Template Hierarchy

Before looking at the different kinds of template files in detail, it’s helpful to know exactly how WordPress decides which one to use on any given page on your website.

WordPress uses the template hierarchy, which is a list of the different kinds of template files, in order. WordPress will always use the most specific file for the content type being displayed, with index.php as the final fallback. Which is why every theme needs an index.php file – in theory, you could just have that file and use it to display all of the content in your site. In practice, it’s better to use multiple template files.

Here’s an example to illustrate how it works.

Let’s say someone is viewing the ‘WordPress’ category archive on your site. WordPress will look for the relevant template file in a particular order, and use the first one it finds to display the content:

A category template file for that specific category, which is named using the category slug. In this case, it would be category-wordpress.php.
A general category template file: category.php.
An archive template file: archive.php.
The index file: index.php.

So if your theme has an archive.php file and a category.php file as well as index.php, it will use category.php.

Now let’s take a look at your contact page, which has the slug contact. WordPress will look for these files, in order:

A custom page template, if you have assigned one to your page in its editing screen.
A page template for that specific page using its slug – so in this case it would be page-contact.php.
A general page template – page.php.
The template file for all singular posts of any post type, including pages – singular.php.
The fallback index.php.

In the themes that I write, I always include a page.php file. This reflects the fact that pages need to be displayed differently from posts.

WordPress will work through the hierarchy for archive files and single posts of any post type in a similar way – it’s worth familiarizing yourself with the hierarchy before you start creating template files, so you know how they’ll be used.

Single Template Files in Detail

When displaying any kind of single post, page or post of a custom post type, WordPress will use a template for a single post. That could be specific to the individual post, to the post type, or just the singular.php or index.php file.

The single template file will include the following:

A call to the header file using get_header().
A loop to output the post title and its content. For single posts, the file will often include metadata such as the date, categories etc.
A call to the sidebar file using get_sidebar(). If you create a custom page template for full-width pages, this won’t be included – or it will but the sidebar will be styled differently so it appears beneath the content instead of next to it.
A call to the footer using get_footer().

Of course, the specifics of what’s included will vary according to the post type and the requirements of your theme. For example, the metadata will be different for different post types and you might include the featured image (also known as the post thumbnail) in some post types but not others.

Here are the different kinds of single template you can create, in the order in which WordPress looks for them in the hierarchy:

For posts, WordPress will look for a custom post template with the name $custom.php (i.e. any name you give it), if that template has been selected in the editing screen, then single-post.php, then single.php, followed by singular.php and finally index.php.
For static pages, WordPress will use a custom page template, if you have assigned one to your page in its editing screen, followed by a page template for that specific page using its slug, then page.php, singular.php and index.php.
For attachments (i.e images), WordPress will look for a $mimetype-$subtype.php file first, where $mimetype is the type of attachment (e.g. image or video) and $subtype is the file type (e.g. png or jpeg). This is followed by $subtype.php, then $mimetype.php, attachment.php and finally single.php, singular.php and index.php.
For custom post types, WordPress will look for a template for that post type with the slug of the specific post (single-$postytpe-$slug.php), followed by single-$posttype.php, single.php, singular.php and finally index.php.

Note: It’s easy to get confused between single.php and singular.php. The single.php file applies to all post type except pages, and is equivalent in the hierarchy to page.php. The singular.php file applies to both posts and pages, and is the last option before index.php.

Archive Template Files in Detail

Archive template files work slightly differently from single template files in that they’re designed not for reading a post (or page) but for providing a list of posts that people can then click through to.

Archive template files will still include the header, footer, and sidebar, but the loop will probably be different in one or more of a number of ways:

You might output the excerpt instead of the full content. Some themes output the full content on archive pages but in my view, this is less user-friendly than the excerpt.
If you’re including the featured image, you won’t want to output it at full size but instead at thumbnail or medium size.
You may want to display different metadata.
You’ll output the title of each post in a lower heading tag than for a single post. For example, you might output the post title on a single page or post in a h1 tag but in an archive template, you put the main page heading in a h1 tag and the post titles in a h2 tag.

You’ll also need to add a title for the archive before the loop; how you do this will depend on the type of archive you’re creating.

Here’s what WordPress looks for when displaying archive pages:

Author archives: author-$nicename.php, where $nicename is the name the author uses on the site; then author-$ID.php, where $ID is the author’s ID, followed by author.php, archive.php and finally index.php.
Category archives: category-$slug.php, using the slug for that category, then category-$id.php, followed by category.php, archive.php and index.php.
Tag archives work in the same way as category archives, substituting tag for category in the filenames.
Custom post type archives: archive-$posttype.php, where $posttype is the ID of the post type used when registering it. This is followed by archive.php and index.php.
Date archives: date.php, then archive.php, then index.php.
Custom taxonomy archives: taxonomy-$taxonomy-$term.php, where $taxonomy is the slug for the taxonomy and $term is the slug for the currently displayed term in that taxonomy, followed by taxonomy-$taxonomy.php, then taxonomy.php, archive.php and index.php. So if you had a product_type taxonomy and a widget term in it, the files WordPress would look for are taxonomy-product_type-widget.php, then taxonomy-product_type.php, then taxonomy.php, archive.php and index.php.

Note that all archive files will default to archive.php before index.php. so it’s a good idea to add this file to your theme at the very least.

The Home Page and the Main Blog Page

If the front page is a static page or a list of your posts, then the first template file in the hierarchy is front-page.php. I often use this to display the contents of a static page using a standard loop, then add one or more instances of WP_Query to output recent posts as well.

If your home page is a static page and there is no front-page.php, then WordPress will use a page template, in the same way as it would for any normal page.

If your home page is also your blog page, WordPress will look for home.php next, followed by index.php.

If your home page is a static page, WordPress will use home.php for your main blog page, followed by index.php. Note that none of your other archive template files are used for the main blog page, so don’t expect your archive.php file to be used there.

Special Templates in Detail

The 404 page has its own template file designed to be displayed when there’s an error. If you don’t create one, WordPress will fall back to the index.php file, so you’ll need to include an error message in that, inside the is_404() conditional tag.

It’s a good idea to create a 404.php template file so you can include extra content designed to help people who have hit an error, such as a search box or a list of your site’s most recent posts. This means people have somewhere to go from the error page and you’re less likely to lose them.

Another special template is the search.php file. This includes a loop outputting the results of the search plus introductory text explaining what’s listed. You could also add extra content such as a list of your most recent posts in case the search doesn’t produce any results.

Template Parts in Detail

Template parts help you make your code more efficient. By separating out parts of the code that are included in multiple template files, you only need to write the code once.

The most commonly used template parts are:

header.php – for everything from the opening of the page to the end of the page header. This will include the head section, the opening of the body section, the header element and your main navigation.
sidebar.php – for the sidebar widgets.
footer.php – for the page footer (the footer element), the wp_footer hook and the closing tag.
loop.php – for the loop. Coding this once means you can use the same loop in multiple template files, and you only have to edit it once if that becomes necessary. You can create multiple versions of the loop for different kinds of content and call them from the relevant template files, such as one for single posts, one for pages and one for archives.

The header, sidebar and footer files each have their own template tag you use to include them in your template files: get_header(), get_sidebar() and get_footer(). For the loop, use get_template_part( 'loop' ) to include a file called loop.php.

Understanding Template Files Will Help You Build Themes

This post was designed to help you understand theme template files and how they work. You now know what they consist of, what they’re designed to display and how WordPress decides which one to use. This will help you decide which files to add to your own themes and code them effectively.

If you’ve created your own themes, how have you used WordPress templates to improve the user experience?

Tags: