How to Create WordPress Custom Page Templates (& Why) • WPShout

There are many many ways you can change the look of a specific page on your WordPress site. You can change the content inside the WordPress content editor. You can change the CSS rules that affect the site. Or create a new file in your WordPress theme’s template hierarchy to correspond to the specific page. Or you can use a theme page template designed specifically for that page. The last one is what we’re talking about here. In this tutorial we’ll cover both how to create a WordPress custom page template, and why you might want to do that. We’ll start with the why.

When you say “WordPress Theme Custom Page Template”, what do you mean?

There’s a huge terminology problem with this topic. As I hinted at above, there are a lot of things with the vague notion of “page” and “template” in the WordPress world that aren’t what we’re talking about here. The first thing I *don’t* mean when saying “WordPress custom page template” is “a WordPress theme.” (Many people new to WordPress say “templates” when they mean “a WordPress theme.”)

So what do I mean by “custom page template”? I mean what is shown at right. For example, you’re editing the Page content type in WordPress (although, as we’ll see later, it can now include other WordPress content types). And while editing your page, you notice the “Page Attributes” box, And within that, you might (dependent on if your theme already has these templates) see this “Template” dropdown. This selection box is illustrated on the right (it’s also on the right side of your “page editing” screen). If you see this dropdown, it’s because your theme provides some of these “custom page templates.” They’re actually files in your currently active theme’s folder (or its parent), and have a single distinguishing feature we’ll come to later. But this selectable dropdown of named page templates is what we’re talking about here today.

How Does This Fit Into the Template Hierarchy?

I’ve written before, and I’ll likely do so again, about how the template — there’s that word again — hierarchy is really the key concept you need to understand to build or modify a WordPress theme. (Here’s our quick intro to it.) Almost everything else is a detail you can work out once you’ve understood the basic dynamic of the template hierarchy. The specific thing we’re meaning today, though, sits outside of the template hierarchy. This “selected template” essentially replaces the whole selection process of the template hierarchy.

If a Custom Page Template was selected in the dropdown we showed above, that “template” file will be used. Full stop, no exception.

To restate that, if a custom page template is selected, that “template” file will be used. Full stop, no exception. If not, then the WordPress template hierarchy will look for a somewhat different way that someone might have tried to style a specific page — with a page-123.php or page-custom-template-utilizer.php file. (The difference between the Custom template, and one with this page-$id or page-$slug structure is really only in interaction and interface.) If neither of those is found, WordPress will fall back to page.php, if it exists, and if not we’d end up at the ultimate fallback, index.php.

If you’re wondering why you’d use this method as opposed to the numeric or slug one — in either case you’re creating a custom file in your theme, after all — the reason is that using custom templates gives you more flexibility and independence between your theme and your site’s database and content. For that reason, I’d recommend it in just about every situation when you’re unsure which to go with. With the numeric or slug-based page-*.php structure, you’re forced to make your theme know about the specific way your WordPress database data is right now. (So if you reuse the theme on a different WordPress site, for example, that file is useless.)

How Do I Make a WordPress Custom Page Template?

OK, so we know that custom page templates will supercede the WordPress template hierarchy. And that we’ll make use of them on actual pages of our WordPress site by selecting them from a “Template” dropdown menu on the right-bar of the relevant piece of content. So it’s time to get to the process for creating a WordPress custom page template.

What you’ll do is, add to your theme (and it really should be a child theme unless there’s a very strong constraint making that impossible for you) a file with a name like my-template.php or really-cool-awesome.php. It doesn’t really matter, as long as you don’t actually use a name that’s part of the template hierarchy, you’re golden. (Which means: do not use a name like page-whatever.php. As we touched on above, WordPress’s template hierarchy thinks it owns a file named with that pattern.)

Once you’ve got the file (cool-page-template.php, of whatever you prefer), you should start it like this:

<?php
/*
Template Name: Name To Appear In The Dropdown
*/
?>
This is my custom template.

And you’re basically done. As you can probably guess, the name that will appear in the “Template” drop down is what I cleverly called “Name To Appear In The Dropdown.” Just like your theme’s style.css file, or a plugin’s main file, WordPress uses the information inside this code comment to provide it with context to work.

Then the content of our pages will, in this case be the very basic HTML text “This is my custom template”. As you might guess, here is where you’re much more likely to put the HTML contents you want to appear on the page. So your <h1> tags, <p> tags, and perhaps (if you’re fancy 🤪) some PHP to do custom behavior you want to show off.

Why Your WordPress Custom Page Template Doesn’t Show Up

I’ve (more than once) had the experience that my new WordPress page template doesn’t show up. By far the most common cause is that I’ve typoed (or misremembed) what the file header comment should look like. It needs to be labelled with the precise right title. So Template Name: Narrow Page is perfect, but WordPress will never locate something that’s instead got a header of Template: Custom.

There are a few other things to check on. Other reasons you might find that your custom page template isn’t showing up:

• You put the file in the wrong place (it needs to be in your current running theme, or its parent)
• You gave your template a file that starts with page-. Because of a feature of WordPress themes, custom page templates that start with page- are instead treated as page of the template hierarchy.
• Your theme is missing one of its two require files, and so isn’t working. (WordPress themes *must* have an index.php file and a style.css.)
• There was an issue with this back in the days of WordPress 4.9 (some years ago now)

Page Templates for non-“Page” WordPress Custom Post Types

For a large part of WordPress’s history, these “custom page templates” were only for the “Page” content type. (WordPress only has two content types, “Posts” and “Pages” by default.) But in WordPress 4.7, the feature was added that you could use these page templates with new content types (often called “custom post types”).

To do this, you add another line to your “file header.” So it’d look a little like this:

<?php
/*
Template Name: Narrower Template
Template Post Type: post, page, event
*/
// Page HTML and PHP goes here...

As you can likely guess, this new Template Post Type: header prefaces the “code-level” name for the (custom) post types. You’ll note that in the above example, we list the page content type that WordPress ships with, as well as the post one. In addition, we’re supporting a third “custom post type” called event.

A Great Reason To Use Custom Page Templates

Now if you’ve done this before, you’ll notice that the page above will have no styling, and look very very little like the rest of your WordPress site (unless you have the simplest theme imaginable). That’s because our file has one simple thing in it, and lacks functionality very common in all other theme pages. It has no get_header(), get_footer(), or The Loop, calls that all your other theme files likely do.

Sometimes you want a page that’s not much like the rest of your site, but still a part of your WordPress management experience. These custom templates are perfect for that.

But it illustrates one of the great powers of custom templates like these as well: sometimes you want a page that’s not much like the rest of your site, but still a part of your WordPress management experience. These custom templates are perfect for that. While you see them used also for archives pages, or (less commonly) contact pages, this ability is often overlooked.

And Finally, Some Practical Advice About Page Templates

When you’re looking to make page that looks just like your other pages (but a little different) I’d actually start by copying an existing file from your theme, probably page.php. This is simply because most of us find it easier to change something than to build from scratch. The code example gives your page template that “blank white page” sense, where you’re probably looking to add or remove some specific details from your existing page.php template. Removing the sidebar or the footer, for example, are very common reasons that people make a “custom page template” in WordPress.

As we’ve covered, if you duplicate your theme’s page.php file to start making your custom page template, you’ll need to make sure you add the “custom page template header” we’ve got above. Again, those are the “magic” page that makes these templates just work. Now, go make awesome pages!

Image credit: Infrogmation