How to Create a Custom Page Template in WordPress

Page templates are one of the most important tools for website creation. They allow us to alter the design and even the functionality of a certain page. With a WordPress custom page template, you can add additional sidebars, place widget areas above or below the page content, have sections for custom post types like portfolios within your pages, and more. In a word, you can create a blank canvas template and design all parts of your page from scratch.

However, creating custom page templates in WordPress does require some programming skills. That is why many are dissuaded from it and choose to use third-party page builder plugins for creating pages. But, we believe that WordPress custom page templates aren’t that hard to create and hope that you will think the same after reading this article. Moreover, the knowledge of creating a custom page template can come in handy in cases where page builders aren’t enough to achieve the desired page layout, so this opens additional room for customizing your entire site.

How to create a custom page template in WordPress

Once you’ve understood why custom page templates are useful, we can dive into how to create them using custom code. We will explain more about the structure of those templates, mention some potential uses, as well as show several examples to illustrate the points we made.

Understanding page templates

In general, page templates serve to display various kinds of dynamic content on your website page. But, custom page templates are at the top of the Template Hierarchy when it comes to displaying that content on a single page. Meaning, WordPress will check whether a custom page template is selected on a given page and use it over any existing page template file that your theme may have. The hierarchy for single pages in WordPress goes like this:

As you can see above, custom templates are the only files that don’t need to follow a specific naming rule to be acknowledged as template files. Let us discuss why this is the case.

A custom page template has two distinct parts—a template header, which registers the template, and the code that creates the content of the page, which is displayed when that page template is selected. The template header is a simple comment that specifies the template name. Other than that, it can have additional information like the theme name or description, for example.

The comment starts with the label Template Name: after which the name of the template is written. Additionally, the custom template should start with the opening PHP tag <?php, while the closing PHP tag could come right after the comment, later in the file, or not at all, depending on the structure of the remaining code.

Example:

<?php /* Template Name: My Custom Template */ ?>

Using the above-mentioned template header, you can register a custom page template with the name My Custom Template. Generally, when naming a custom page template, you should strive to make the name easy to understand. This is because the name you give your template is the one that will be displayed as an option in the Page Attributes dropdown on a single page. As such, the name of the template should be straightforward and clear to anyone using it.

Additionally, since the WordPress 4.7 update, you can create custom templates for other post types. To do so, you need to specify which post type(s) the template is being created for. This is done by adding the label Template Post Type: followed by a list of post types that you want this template to be available for.

To clarify further, here’s an example of a template header for the Full Width Template taken from the Twenty Twenty theme. The template is made for both pages and posts, meaning it can be selected from the Page Attributes section on pages, as well as from the Post Attributes section on posts.

<?php
/**
* Template Name: Full Width Template
* Template Post Type: post, page
*
* @package WordPress
* @subpackage Twenty_Twenty
* @since Twenty Twenty 1.0
*/

With this information, you should be ready to start making your own template headers. So, in the following sections, we can focus on the page templates themselves.

In terms of the code that goes below the template header and creates the page content, there are a lot of things that you can include. For example, content inserted in the editor, sidebars, various widget areas, content related to a custom post type, additional content based on a conditional statement that needs to be met, etc.

The possibilities for creating distinct custom page templates are near endless and depend only on what you need and your programming skills. One way of starting to create that code is to take your theme’s existing page templates and copy and paste them into a new file where you can edit their code. Alternatively, we made several examples of page templates for this article that you can use. We will cover them in the following section.

However, there are additional things we must discuss before delving into those examples. In the end, when you’re done creating the code, the final steps include saving the file as a .php file and then uploading it in the correct place within your theme. As we mentioned before, custom page templates don’t need to be named a certain way to be interpreted as template files. However, this also means you can’t name them using any of the reserved words—page, singular, index—or name them using the prefix page– as WordPress will interpret them as specialized templates, intended for one page only. We suggest naming the files the same as the templates so that you can keep track of those files more easily.

After naming the custom page template file, you will need to upload it to the server via FTP. WordPress recognizes the following spots as valid for uploading a custom template file: active parent theme directory, active child theme directory, or a subdirectory in either of those two locations.

Examples

Now that you understand more of the details behind custom page templates, we can delve into the examples we made for this article. You can use them as a guideline for creating your page templates or modify them to your liking.

Depending on the template, some additional CSS code might be needed to adjust your page template stylization. We will also show you the CSS we used in the cases we found it needed to be added. However, we should note that this CSS shouldn’t be applied to all websites. In general, CSS is tailor-made on a case-by-case basis since it needs to fit a particular site. As such, you should strive to create your own CSS codes, if you need to further stylize the page. With that being said, let us begin.

The following code represents a template called No Sidebar Page Template. This is a rather simple template. It uses the get_header() and get_footer() function that loads the existing header and footer template files from the theme you are currently using. As for the main page content, by using the_content() function within a WordPress Loop, you are making sure that what was inserted in the editor is displayed on the page. Apart from that, the page will have a comment section below, as long as there are existing comments made on that page or if comments are allowed on that page. Essentially, what separates this page template from the ones that are commonly used is that we have removed any sidebars, hence the template name.

<?php
/*
Template Name: No Sidebar Page Template
*/
get_header();
?>
<main id="main-content" class="custom-grid">
<div class="custom-grid-inner">
<?php if ( have_posts() ) {
while ( have_posts() ) : the_post();

the_content();

if ( comments_open() || get_comments_number() ) {
comments_template();
}
endwhile; // End of the loop.
} ?>
</div>
</main>
<?php
get_footer();

Since this is a very simple template, we didn’t need any additional CSS to stylize it. Thanks to the CSS classes that were used in the theme’s header and footer templates, the page was sufficiently stylized all by itself. Below, you can see an example of how a page with this page template assigned to it could look. In this case, the template was used with the Lekker theme, and it shows that theme’s style.

This code represents a page template called Blank Page Template. Unlike the other page templates we created for the article, this one doesn’t load the header and footer templates of your current theme. More precisely, it represents a template for a page that doesn’t have a header or footer. Such pages are often used as landing or maintenance pages.

As this template doesn’t rely on loading previously created template files, you would need to add the whole HTML structure of the page, created through a mix of HTML and PHP code. The bulk of the code we created is within the <head> and <body> tags, with only the language_attributes() being used within the <html> tag.

Inside the <head> tag, we added the metadata on encoding for pages and feeds using the bloginfo() function. We also added the metadata for responsiveness—the site will adapt based on the width of your device; it is loaded at an initial zoom of 100%, but it can be zoomed in and out freely. This is done by setting the user-scalable parameter to yes, instead of no which is present on numerous themes. Finally, we enabled the profile that inserts richer metadata on the site. After that, we added a part regarding pingbacks and trackbacks. Even though this is primarily useful for posts, we decided to include it as it could be handy if you decide to make this template available for both pages and posts. Finally, we used the wp_head() function, which prints scripts or data on the front end before the closing </head> tag.

The <body> tag contains the classes that are printed thanks to the body_class() function, and which can be later used for creating targeted CSS code. Apart from that, we added the itemscope and itemtype variables and the wp_body_open() function that allows users to add scripts directly inside the body tag, as of the WordPress 5.2 update. Additionally, the main content of the page is found within the body tag. And that content is rather simple, it only contains what has been added directly through the editor thanks to the use of the function the_content(). Finally, we used the wp_footer() function, which prints scripts or data on the frontend before the closing </body> tag.

<?php
/*
Template Name: Blank Page Template
*/
?>
<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>
<meta charset="<?php bloginfo( 'charset' ); ?>">
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=yes">
<link rel="profile" href="https://gmpg.org/xfn/11">

<?php if ( is_singular() && pings_open( get_queried_object() ) ) { ?>
<link rel="pingback" href="<?php bloginfo( 'pingback_url' ); ?>">
<?php } ?>

<?php wp_head(); ?>
</head>
<body <?php body_class(); ?> itemscope itemtype="https://schema.org/WebPage">
<?php
// Hook to include default WordPress hook after body tag open
if ( function_exists( 'wp_body_open' ) ) {
wp_body_open();
}
?>
<div id="page-wrapper" class="custom-page-wrapper">
<div id="page-wrapper-inner" class="custom-page-wrapper-inner">
<main id="page-content" class="custom-grid">
<div class="custom-grid-inner">
<?php if ( have_posts() ) {
while ( have_posts() ) : the_post(); 
the_content();
endwhile; // End of the loop.
} ?>
</div>
</main>
</div>
</div>
<?php wp_footer(); ?>
</body>
</html>

In this case, we only needed a small amount of CSS to adjust the stylization of the page. This is what we ended up using:

#page-wrapper {
padding: 50px 0 40px;
}
.custom-page-wrapper-inner {
padding: 0 10px;
}

Here’s an example of a page with this template, after adding the above-mentioned CSS.

This code represents a page template called Content Bottom Template. Similar to our first example, this template loads the appropriate header and footer template files of your current theme using the get_header() and get_footer() functions.

As for the main page content, it is divided into two parts. The first part contains what was inserted in the page editor, followed by a section we called Content Bottom, that gave this template its name. This section displays what was inserted in a custom widget area whose ID is new-widget-area. Thanks to the use of the dynamic_sidebar() and is_active_sidebar() functions, the Content Bottom section is shown only if the widget area, which has new-widget-area as its ID, was registered and if it isn’t empty.

Then, as with our first example, the comment section is shown only if there were previously posted comments on that page or if commenting was allowed. As for the second part, it simply loads the sidebar template of your current theme, using the get_sidebar() function.

<?php
/*
Template Name: Content Bottom Template
*/
get_header();
?>
<main id="main-content" class="custom-grid">
<div class="custom-grid-inner">
<div class="main-section">
<?php if ( have_posts() ) {
while ( have_posts() ) : the_post();

the_content();

if ( is_active_sidebar( 'new-widget-area' ) ) { ?>
<div class="content-bottom">
<?php dynamic_sidebar( 'new-widget-area' ); ?>
</div>
<?php }
if ( comments_open() || get_comments_number() ) {
comments_template();
}
endwhile; // End of the loop.
} ?>
</div>
<div class="main-sidebar">
<?php get_sidebar(); ?>
</div> 
</div>
</main>
<?php
get_footer();

Although the page will have two distinct parts thanks to this template—the main section and the sidebar—all content will be displayed in succession. Meaning, each section will fall below the one before it, which is not the layout we want to achieve. So, we needed to stylize this template further, and we used the CSS shown below to do that.

This CSS makes the main section take up three-quarters of the page, while the sidebar occupies the remaining one-quarter of screen sizes greater than or equal to 1025px. We included some padding on both sides of the two parts of the page to visually separate them. Also, we added a small margin above and below the content bottom section, for similar reasons.

@media only screen and (min-width: 1025px){
.main-section {
width: 75%;
}
.main-sidebar {
width: 25%;
}
}
.main-section, .main-sidebar {
float: left;
padding: 0px 15px;
}
.content-bottom {
margin: 30px 0;
}

Here’s how a page with the Content Bottom Template and added CSS would look like on the Lekker theme.

Final Thoughts

Creating a WordPress custom page template will open a whole new world of customization options for you. Depending on your coding knowledge and comfort level, the possibilities can be numberless. Therefore, it comes down to carefully deciding on the page layout you wish to have and adding the appropriate code for all the sections you wish to include.

Page templates can be summed up as having two parts—the header and the code that creates the page content. We hope that our examples have given you an idea of what those two should look like. Use that information as a guideline and improve on the code we provided and start making your own custom post type templates.