The Ultimate Guide to WordPress Page Templates

One of the templates that I always include in any theme I code is the page.php file.

This is the template that WordPress will use for creating static pages. It’s useful to have a dedicated page.php file instead of falling back to index.php because you’ll need your pages to display slightly different content from single posts.

For example in a post you’ll generally include metadata such as the post date and the categories that the post has been added to, but in a page you won’t.

WordPress also lets you take page templates a step further, by creating custom page templates. You can use these to create multiple page templates that you select from when setting up a new page in your admin screens, or even to create a page template that’s automatically used by just one page on your site. Clever, huh?

In this post I’ll guide you through the options for page templates and show you how to code them. But first, let’s delve into the WordPress template hierarchy to discover which template files WordPress uses when displaying static pages.

How WordPress Selects Templates for Static Pages

As with all other types of content, WordPress will use the template hierarchy when deciding which of the template files in your theme (or its parent theme, if it has one) to use when displaying a static page on your site.

The hierarchy works in this order:

  • If there’s a custom page template file, and you’ve selected it for that page, this will be used in preference to other files.
  • If there’s no custom page template (or if there is but it’s not selected for this page), WordPress will use the page-$slup.php file, where $slug is the slug for that page. So if you’ve created a page-contact.php file and you have a page with the slug contact, it’ll use that.
  • Next it looks for a page template called page-$ID.php, where $ID is the ID of the page. This is similar to using the slug – the main difference is that if you change the page’s slug in the admin it will still use this template file, whereas it will stop using the slug template file.
  •  If none of the above exist and there’s a file called page.php, it’ll use that.
  • If there’s no page.php file, it’ll use singular.php if you have one. This file displays single posts and pages.
  • If none of the above files are in your theme, it’ll revert to using index.php.

So there are no less than six files you could include in your theme for a given page. In fact you may have more than six page templates in your theme if you have multiple custom page templates or multiple templates using the slug or the ID. It’s up to you to decide how specific you want to be.

Now let’s take a look at how you create a page template file.

Creating a Generic Page Template File

The template file for pages most commonly included in themes is page.php. If this is the only file you have for displaying pages (as opposed to posts), then it’ll be used for every static page on your site.

To create this template file, you simply create a file in your theme called page.php. I often start with my index.php or singular.php file, make a duplicate which I call page.php, and then edit it to remove elements I don’t want. These will include:

  • post dates
  • post categories and tags
  • other metadata such as the author
  • a link to the previous or next post.

Creating a clean page.php file like this makes things more efficient.

The page.php file in the framework theme I use for all my WordPress projects is very simple:

This consists of four things:

  • a call to get the header file
  • a loop, which includes a file called loop-page.php
  • a call to the sidebar file
  • a call to the footer file.

The loop.php file contains just those parts of the loop that are relevant to static pages:

Note that it’s got one conditional tag, which displays the page title on pages other than the home page. Apart from that it’s a pretty standard loop.

Creating a Custom Page Template File

Another option I use a lot in my themes is custom page templates. You can use these to output different content on different pages or for differences in layout.

In many of my themes I have a page template for full width pages, which is different from the normal page.php file in that it doesn’t include the call for the sidebar. Or it might do that, but use different CSS classes so I can display the widgets in the sidebar below the main content instead of to the right.

In my theme I have a file called template-page-full-width.php that is a custom page template. Here’s the code, which is very similar to page.php but without the sidebar:

The part of this file that tells WordPress it’s a custom page template is the line with Template name at the beginning. I can then select this from the page editing screen in the WordPress admin:

Selecting a custom page template in the page editing screen

I’ve created  a few page templates in my site: Full width page is the one above. Note that you’ll also need to amend the styling for your content and sidebar in that template file. In your style.css file, you’ll need something like this:

It’s important not to start the name of your custom page template files with page-. This is because that could clash with a page slug or page ID template file that you create in the future. Imagine you created a page-full-width.php template file for the above scenario. Then imagine that you or someone else editing your site created a page with the slug full-width. That page would automatically use the page-full-width.php template file because of the slug. So pick a prefix you’ll use for all your custom page templates (which isn’t page-) and use it.

Creating a Targeted Page Template File

The other option you have is to create a template file for one specific page in your site. You can either target the page by slug or by ID.

So let’s say I wanted to create a specific page template for my contact page. My page has a slug of contact and an ID of 20. I could create either a page-20.php file or a page-contact.php file.

You don’t need to include any special commented out text at the top of your file – although I would recommend it as a note to yourself in case you come back to edit this file in the future and can’t remember what it was for.

Choosing whether to target the slug or ID will depend on two things:

  • If you think there’s a risk the page slug could be changed in future (more likely if multiple people manage the site), then use the ID.
  • If you think the ID could change in the future (more likely if you’re planning to migrate the site in a way that won’t preserve post IDs, such as using the Importer tool instead of exporting and importing database files), then target the slug.

A targeted page template file is useful if you want to display extra content on a given page in your site. So on my site I have one page that runs the standard loop and then runs another loop using WP_Query to list all of the books I’ve published. For this I’ve created a custom page template (using the technique above). But if I was sure I didn’t want to use this technique for any other page in the future, I could remove the commented out text and rename the file page-books.php, with books being the slug for my page.

This is a good idea if other people will be managing your site and adding pages, and you’re not sure they won’t select the wrong custom page template in the page editing screen. It also reduces any confusion.

Page Templates Give You Lots of Flexibility

Page templates are a useful element of the WordPress theming system. They let you display your static pages differently form single posts and archive pages, and they also give you additional features you can use with individual pages.

Try using custom page templates or targeted page templates to customize the way your pages are displayed – it can be very powerful.

Rachel McCollin
How will you use page templates to improve the structure of your site?