How to Create a Custom WordPress Page Template (Step by Step)
Learn how to create a reusable custom WordPress page template using PHP, assign it in the page editor, and style it with CSS while keeping Gutenberg content editable.
Youtube Video
Intro
A custom page template lets you give selected WordPress pages a different layout without changing the default page design across the rest of your website. For example, you might need a landing page with a wider content area, a portfolio page with a special structure, or a contact page with its own spacing and styling.
In this tutorial, we will build a Custom Landing Page template using PHP, make it selectable in the WordPress Page editor, and add a little CSS. The page title and content will remain editable in the Block Editor (Gutenberg).
The demonstration uses the Astra theme, but the same basic approach applies to classic WordPress themes and classic/hybrid themes that support PHP page templates. It does not describe the HTML template workflow used by modern block themes in the Site Editor.
What you will build
By the end of the tutorial, you will have:
- A reusable PHP page template named Custom Landing Page.
- A template that reuses the active theme’s header and footer.
- A main content area that displays the current page’s title and Gutenberg content.
- A selectable Template option in the WordPress Page editor.
- Template-specific CSS that does not unintentionally restyle ordinary pages.
- A simple way to verify that WordPress is using the custom template.
We will use the WordPress Loop, get_header(), get_footer(), the_title(), and the_content() to do this.
1. Before you start
You will need a working WordPress installation, an active classic or PHP-based hybrid theme, access to your theme files (for example through VS Code), and permission to edit a test page in WordPress.
A classic theme commonly includes files such as:
my-theme/
├── style.css
├── functions.php
├── header.php
├── footer.php
├── index.php
├── page.php
└── single.php
Some themes organize their files differently, but the principle is the same: a PHP template provides the layout, and WordPress provides the content.
Important: use a child theme on a real site
The video demonstration inspects and edits files inside the Astra theme directory to show how templates work. For production sites using a third-party theme such as Astra, add your custom template to a child theme instead of editing the Astra parent theme. A parent theme update may overwrite files you added or changed there.
For the code samples below, my-theme means the active theme or, preferably, its properly configured child theme. This is a reusable educational example, not an instruction to change the Web Dev Guru site’s own theme.
2. Locate your active theme folder
First, check which theme is active under WordPress Dashboard → Appearance → Themes. Then open the corresponding folder in your editor. Theme files are usually stored here:
wp-content/themes/
For example:
wp-content/
└── themes/
└── my-theme/
├── page.php
├── functions.php
└── style.css
If you are using an Astra child theme, open the child theme’s directory for the custom file. The template should be available through the active theme; do not accidentally save it inside an inactive theme.
3. Understand the default page.php
Before creating a new file, inspect the theme’s existing page.php. Its exact code may be more complex than this simplified example:
<?php
/**
* Default page template — simplified example.
*/
get_header();
?>
<main id="primary" class="site-main">
<?php
while ( have_posts() ) :
the_post();
the_title( '<h1>', '</h1>' );
the_content();
endwhile;
?>
</main>
<?php
get_footer();
This example contains four key elements:
get_header()loads the theme’s shared header, which usually includes the site navigation.while ( have_posts() )andthe_post()form the WordPress Loop, which makes the current page available to template functions.the_title()andthe_content()display the page title and the editor content.get_footer()loads the shared theme footer.
Our custom template will use these same building blocks. We do not need to copy Astra’s entire page.php implementation to understand the basic mechanism.
4. Create a new PHP template file
In the root of the active classic theme or child theme, create:
page-custom-landing.php
The example directory now looks like this:
my-theme/
├── footer.php
├── functions.php
├── header.php
├── index.php
├── page.php
├── page-custom-landing.php
└── style.css
The filename is descriptive so the purpose of the file is easy to recognize later. WordPress uses a comment inside the file to identify its human-readable template name.
5. Register the template with Template Name
Start the new PHP file with this header:
<?php
/**
* Template Name: Custom Landing Page
*/
The important line is:
* Template Name: Custom Landing Page
WordPress reads this file header and adds Custom Landing Page to the available templates in the Page editor. The text after Template Name: is the label an editor will see.
The filename and label serve different purposes: page-custom-landing.php is the actual file, while Custom Landing Page is the selectable name. They do not have to match exactly.
Add a basic security check
Just below the header, add:
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
WordPress defines the ABSPATH constant during normal loading. This guard stops the file if someone tries to execute it directly outside WordPress. It is a simple precaution, not a substitute for normal WordPress security practices.
6. Reuse the header and footer
Next, load the existing theme header:
get_header();
This calls the current theme’s header.php through WordPress’s template system. We can therefore reuse the existing header and navigation instead of hardcoding them into the new layout.
At the bottom of our file we will use:
get_footer();
This similarly loads the theme footer. The custom page content will sit between the header and footer.
Conceptually, our page will look like this:
Theme header
↓
Our custom page layout
↓
Theme footer
7. Add the main content wrapper
Between the header and footer, create a <main> element:
<main id="primary" class="site-main custom-landing">
<!-- WordPress page content will go here. -->
</main>
The <main> element identifies the primary content area. The site-main class provides a conventional theme hook; the extra custom-landing class gives us a specific CSS selector for this template.
Later, a rule such as .custom-landing .page-title will affect the title inside our custom template rather than the titles of every page on the site.
If a particular theme already prints its own <main> element around a page template, adapt the wrapper to avoid nested or duplicate main landmarks. The example assumes that the template is responsible for this content wrapper.
8. Add the WordPress Loop
Inside <main>, add the Loop:
<?php while ( have_posts() ) : ?>
<?php the_post(); ?>
<!-- Page title and content will go here. -->
<?php endwhile; ?>
Here is what happens:
have_posts()checks whether the current request has content to display.the_post()advances the Loop and sets up the current post/page for template functions.- The code between these statements and
endwhileis rendered for the current page.
A normal WordPress Page typically produces a single iteration of this Loop, but the structure follows WordPress’s familiar template pattern.
**Why the_post() matters:** Functions that work with the current page expect WordPress to have prepared that page first. Omitting the_post() is a common beginner error.
9. Display the page title
Inside the Loop, output the title:
<h1 class="page-title">
<?php the_title(); ?>
</h1>
the_title() prints the title defined in the WordPress Page editor. For example, a page named Web Development Resources will display that heading using our markup.
The <h1> is appropriate here because it is the main heading of the example page. Make sure the particular theme does not already output another visible page H1 outside this template.
10. Display editable Gutenberg content
Immediately below the title, add:
<div class="page-content">
<?php the_content(); ?>
</div>
the_content() outputs the current page’s content as rendered by WordPress. This may include paragraphs, headings, images, buttons, columns, galleries, embeds, and other supported Gutenberg blocks.
This is the key separation of responsibilities:
- The PHP template decides where and how the page structure is rendered.
- The WordPress editor controls the text, images, and blocks placed inside that structure.
You do not need to hardcode the contents of each landing page into the PHP file. Different pages can reuse the same layout while keeping their own content.
11. Complete custom page template — PHP
Now combine the pieces into the finished page-custom-landing.php. This is the canonical complete example to copy and review:
<?php
/**
* Template Name: Custom Landing Page
* Description: A simple reusable page template for a classic WordPress theme.
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
get_header();
?>
<main id="primary" class="site-main custom-landing">
<?php while ( have_posts() ) : ?>
<?php the_post(); ?>
<h1 class="page-title">
<?php the_title(); ?>
</h1>
<div class="page-content">
<?php the_content(); ?>
</div>
<?php endwhile; ?>
</main>
<?php
get_footer();
This file has one <main> element, one WordPress Loop, and the normal title/content functions. It does not register a new post type, add a plugin, or replace the theme’s shared header or footer.
Save the file. For this basic classic-theme template, WordPress reads the Template Name header automatically; no separate plugin or template-registration function is needed.
12. Create or open a page in WordPress
Go to Pages → Add New, or open an existing test page under Pages → All Pages.
You can create a page titled Custom Landing Page Demo and give it sample content such as:
- Heading: Build Better WordPress Websites
- Paragraph: Learn how WordPress templates work and create reusable layouts directly inside your theme.
- Button: Start Learning
These are example Gutenberg blocks. Their purpose is to demonstrate that the page editor still manages its content even when a custom PHP template controls the structure.
You do not need to replace the page’s existing content when you change its template.
13. Select the new template in the Page editor
In the editor, open the Page settings sidebar and locate Template. Depending on your WordPress version, this may appear as a setting or dropdown.
Choose:
Custom Landing Page
This is the label from the PHP file header — not necessarily the PHP filename.
Click Publish for a new page, or Update for an existing one. Then open the page on the frontend.
WordPress should now render the chosen page with our custom PHP file instead of using the regular page.php layout for that page.
14. Check the result on the frontend
You should see the same site header and footer, plus the title and content of the selected page inside the custom content area.
The rendering sequence is approximately:
header.php
↓
page-custom-landing.php
├── Page title: the_title()
└── Editor content: the_content()
↓
footer.php
Check that the page title appears only once and that headings, paragraphs, buttons and other Gutenberg blocks display correctly.
A simple temporary verification
If you are not sure the custom template is being used, temporarily place a visible test paragraph just after the opening <main> tag:
<p>Custom template is active.</p>
Save the file and refresh the frontend page. If the message appears, it confirms the custom file is being rendered. Remove the temporary paragraph after the test so it does not appear on the finished site.
15. Add template-specific CSS
The custom custom-landing class allows you to style the layout without targeting all pages globally.
For example:
.custom-landing {
max-width: 1200px;
margin-inline: auto;
padding: 4rem 1.5rem;
}
.custom-landing .page-title {
margin-bottom: 2rem;
font-size: clamp(2rem, 5vw, 4rem);
}
The first rule gives the content a maximum width, centers it horizontally, and adds internal spacing. The second changes the title’s bottom margin and gives it a responsive font size.
You can add this CSS to your correctly loaded child-theme stylesheet, or use Appearance → Customize → Additional CSS when that feature is available with the active theme. The video demonstration uses the Customizer.
Why the selector matters
Compare these two selectors:
.page-title {
/* Could affect page titles across the site. */
}
.custom-landing .page-title {
/* Targets titles inside this custom template. */
}
The second selector scopes the rule to our custom layout. This is especially useful on sites with several different page templates.
The actual final appearance also depends on your theme’s existing CSS. You may need to adjust the selector or spacing for the theme you use.
16. Confirm the custom template controls the layout
Once the template is styled, return to the Page editor and change Template back to the default template. Update the page and view it again.
The original theme layout should return, while the page’s editor content remains intact. If you switch back to Custom Landing Page, the custom structure and scoped styling should return.
This is the main advantage of the method: you can change the layout assigned to a page without rewriting its content.
17. How WordPress chooses which PHP file to load
For a classic theme, the simplified decision for an ordinary Page is:
Visitor opens a WordPress Page
|
v
Has a custom template been selected?
/ \
Yes No
| |
v v
Load selected Follow normal
PHP template page template hierarchy
|
v
page.php (where applicable)
|
v
fallback templates
A selected custom template takes precedence for that page. Without one, WordPress follows its normal hierarchy, which can include page-specific templates as well as page.php, singular.php, and ultimately index.php, depending on the files in the theme.
This tutorial focuses on an assignable PHP page template in a classic theme, not on building HTML templates through the block-theme Site Editor.
18. Filename versus template name
These values are related, but they are not identical:
PHP filename:
page-custom-landing.php
This is the actual file inside the theme.
WordPress editor label:
/**
* Template Name: Custom Landing Page
*/
This is the human-readable label shown in the editor. For example, a file called landing.php could use Template Name: Marketing Landing Page.
Descriptive filenames and labels make templates easier to understand and maintain.
19. Common problems and how to fix them
The template does not appear in the editor
Check that you saved the file inside the active theme or child theme, not another installed theme. Also confirm that the PHP file has a properly formatted Template Name header and that you are editing a WordPress Page.
The page is blank or a PHP error appears
Review the PHP syntax, opening/closing tags and Loop structure. One missing semicolon, incorrect PHP tag, or unmatched block can break rendering. Start with the complete working example above before adding new features.
The page title or content is missing
Confirm that the_post() is called inside the Loop before using the_title() and the_content(). Also check that the test page actually has a title and content.
The layout or title is duplicated
Check whether the final template accidentally includes two <main> elements, two WordPress Loops, or two title outputs. A theme may also have its own content wrappers and heading behavior; review that integration if you see duplication.
CSS changes affect pages they should not affect
Target the unique custom-landing class rather than generic selectors such as .page-title alone. Check the specificity of existing theme styles if your rules do not seem to apply.
Custom files disappear after a theme update
Customizations placed directly inside a third-party parent theme can be replaced during updates. Use a properly configured child theme for production work.
The site’s theme uses the Site Editor
This PHP example is for classic or PHP-based hybrid theme workflows. A block theme usually manages page templates with HTML templates and the Site Editor, so its editing process differs from this tutorial.
20. When is a custom page template useful?
Custom page templates are helpful when the layout or behavior of a page genuinely needs to be different, for example:
- Landing pages
- Portfolio pages
- Contact pages
- Full-width pages
- Documentation or resource pages
- Pages without a sidebar
You do not need a new PHP template for every page simply because the text changes. Gutenberg already handles per-page content. Create a custom template when you need a reusable structural variation.
21. Final recap
In this tutorial, we learned how to:
- Locate the active classic WordPress theme or child theme.
- Inspect the existing
page.phpto understand its structure. - Create
page-custom-landing.php. - Make it selectable with
Template Name: Custom Landing Page. - Guard against direct access with
ABSPATH. - Reuse the header and footer with
get_header()andget_footer(). - Render the page with
have_posts(),the_post(),the_title(), andthe_content(). - Assign the template through the WordPress Page editor.
- Add layout-specific CSS using
.custom-landing. - Verify that switching templates changes the layout without deleting page content.
The result is a reusable PHP layout with editable WordPress content — a useful foundation for more advanced classic-theme development.