WordPress Page Templates — Complete Guide to Default, Full-Width and Custom Templates

In this tutorial, you'll learn what WordPress page templates are, how the default template works, how to use full-width and custom templates, and how to create your own template files in PHP for specific page layouts.

What You'll Learn

• What page templates are and how they change page layouts
• How the default template (page.php) works
• What a full-width template does (no sidebar)
• How to create custom templates with the Template Name file header
• Template file naming conventions
• How to assign templates in the page edit screen
• Template hierarchy for pages: page-{slug}.php, page-{id}.php, page.php
• How to create a custom template from scratch with PHP

Why It Matters

Every page on your WordPress site can look different. Your Contact page might need a full-width map and form with no sidebar. Your Landing page needs a distraction-free layout with no header menu. Your Portfolio page needs a grid layout. Page templates let you create these different experiences without building a separate theme for each page type.

Real-World Use

A marketing agency's website has: a standard About page with sidebar, a Contact page with Google Maps (full-width, no sidebar), landing pages for each campaign (minimal, no header/footer), and a Portfolio page that displays work in a grid. Each uses a different page template, all within the same theme.

Learning Path

flowchart LR
    A[Managing Pages] --> B[Page Templates]
    B --> C[Media Library]
    B --> D[Image Optimization]
    C --> E[Comments & Discussion]

What Are Page Templates?

A page template is a PHP file that controls how a specific page looks. Templates can change:

• Layout (with sidebar, full-width, grid)
• Which header and footer are used
• Which CSS classes are applied
• What content is displayed (custom loops, forms, maps)
• What functionality is available (comment forms, sharing buttons)

Think of page templates as interchangeable outfits for your pages. The content stays the same, but the presentation changes based on which template you assign.

The Default Template (page.php)

Every theme must have a page.php file. This is the default template used for all pages unless you assign a different one.

<?php
// Default page.php template

get_header();

while (have_posts()) :
    the_post();
    ?>
    <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
        <header class="entry-header">
            <h1 class="entry-title"><?php the_title(); ?></h1>
        </header>

        <div class="entry-content">
            <?php the_content(); ?>
        </div>
    </article>
    <?php
endwhile;

get_sidebar();
get_footer();

This template includes:

• get_header() — loads header.php
• The Loop — displays page content
• get_sidebar() — loads sidebar.php
• get_footer() — loads footer.php

Full-Width Template (No Sidebar)

A full-width template removes the sidebar, giving content the full width of the page container. Most themes include this as a built-in template.

<?php
/**
 * Template Name: Full Width
 *
 * @package ThemeName
 */

get_header();
?>

<div class="content-area full-width">
    <?php
    while (have_posts()) :
        the_post();
        the_content();
    endwhile;
    ?>
</div>

<?php
get_footer();

Note the absence of get_sidebar(). The content div also gets a full-width CSS class, which the theme's stylesheet uses to set max-width: 100%.

When to Use Full-Width

• Landing pages — no sidebar distractions
• Contact pages — full-width map and form
• Portfolio pages — grid layouts need horizontal space
• Coming soon pages — focused message with no navigation

Custom Templates Created in Theme

You can create any number of custom templates. Each needs a specific format at the top of the file:

<?php
/**
 * Template Name: Landing Page
 *
 * Description: A minimal landing page without header navigation or sidebar.
 * Ideal for marketing campaigns and lead generation.
 *
 * @package ThemeName
 */

get_header('landing');
?>

<div class="landing-content">
    <?php
    while (have_posts()) :
        the_post();
        the_content();
    endwhile;
    ?>
</div>

<?php
get_footer('landing');

The Template Name: comment is the key. WordPress scans this file header and adds "Landing Page" to the Template dropdown in the page editor.

Multiple Template Headers

WordPress recognizes several file header fields:

Template File Naming Convention

While you can name template files anything (e.g., landing-page.php, full-width-portfolio.php), common conventions make your theme easier to understand:

You can also use WordPress-specific naming that automatically assigns the template based on slug or ID (see Template Hierarchy below).

Assigning Templates in the Page Edit Screen

1. Open a page in the editor
2. In the Document sidebar, find Page Attributes
3. Open the Template dropdown
4. Select the desired template
5. Update or publish the page

// Programmatically check which template a page uses
$template = get_page_template_slug(get_the_ID());

switch ($template) {
    case 'page-full-width.php':
        echo 'This page uses the full-width template.';
        break;
    case 'page-landing.php':
        echo 'This page uses the landing template.';
        break;
    default:
        echo 'This page uses the default template.';
}

Verifying the Template is Active

After saving, visit the page on the front end. If the template is working, you'll see the correct layout. Common signs something is wrong:

• Page still shows a sidebar → template might not have been assigned properly
• Page looks broken → the template file might have errors
• Page is blank → check for PHP errors

Twenty Twenty-Four Template Examples

The default Twenty Twenty-Four theme (included with WordPress 6.4+) comes with several built-in templates:

These templates are block-based (HTML) rather than classic PHP templates. However, the assignment Process is identical.

Creating a Custom Template from Scratch

Let's build a custom portfolio template step by step.

Step 1: Create the PHP File

Create a file named page-portfolio.php in your theme directory:

<?php
/**
 * Template Name: Portfolio Grid
 * Description: Displays child pages in a grid layout.
 * Suitable for portfolio or case study pages.
 *
 * @package ThemeName
 */

get_header();
?>

<main id="primary" class="site-main portfolio-page">
    <?php
    while (have_posts()) :
        the_post();
        ?>
        <article id="post-<?php the_ID(); ?>" <?php post_class('portfolio-intro'); ?>>
            <header class="entry-header">
                <?php the_title('<h1 class="entry-title">', '</h1>'); ?>
            </header>
            <div class="entry-content">
                <?php the_content(); ?>
            </div>
        </article>
        <?php
    endwhile;
    ?>

    <?php
    // Get child pages for the portfolio grid
    $child_pages = new WP_Query(array(
        'post_type'      => 'page',
        'posts_per_page' => -1,
        'post_parent'    => get_the_ID(),
        'orderby'        => 'menu_order',
        'order'          => 'ASC',
    ));
    ?>

    <?php if ($child_pages->have_posts()) : ?>
        <div class="portfolio-grid">
            <?php while ($child_pages->have_posts()) : $child_pages->the_post(); ?>
                <div class="portfolio-item">
                    <?php if (has_post_thumbnail()) : ?>
                        <a href="<?php the_permalink(); ?>">
                            <?php the_post_thumbnail('medium'); ?>
                        </a>
                    <?php endif; ?>
                    <h3><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h3>
                    <?php the_excerpt(); ?>
                </div>
            <?php endwhile; ?>
        </div>
        <?php wp_reset_postdata(); ?>
    <?php endif; ?>
</main>

<?php
get_footer();

Step 2: Upload the File

Upload page-portfolio.php to your theme directory via FTP or the Theme File Editor:

/wp-content/themes/your-theme/page-portfolio.php

Step 3: Assign the Template

1. Create a new page called "Portfolio"
2. In Page Attributes, select "Portfolio Grid" from the Template dropdown
3. Add child pages for each portfolio item
4. Publish the page

# Verify the template is registered
wp post list --post_type=page --field=post_title,ID
# Then check the template for page ID 123:
wp post meta get 123 _wp_page_template

Template Hierarchy for Pages

When WordPress loads a page, it searches for template files in this specific order:

1. Custom template assigned in the editor → page-portfolio.php (from Template dropdown)
2. Page slug → page-about-us.php (page has slug "about-us")
3. Page ID → page-42.php (page ID is 42)
4. Default → page.php
5. Fallback → singular.php
6. Last resort → index.php

Using the Slug Template

If you name your template file page-about-us.php, WordPress automatically uses it for the page with slug "about-us" — no need to assign it in the editor.

// This file is automatically used for the page with slug "about-us"
// File: page-about-us.php
get_header();
// Custom about page content
get_footer();

Using the ID Template

If you name your template file page-42.php, WordPress automatically uses it for the page with ID 42.

// This file is automatically used for the page with ID 42
// File: page-42.php
get_header();
// Custom content for this specific page
get_footer();

When Hierarchy Matters

The hierarchy ensures that you can override templates at different levels of specificity. For example:

page-portfolio.php  ← Assigned manually (most specific)
page-portfolio.php  ← Matches the slug "portfolio"
page-42.php         ← Page ID is 42
page.php            ← Default for all pages
singular.php        ← Fallback for all single content
index.php           ← Ultimate fallback

WordPress stops at the first match and uses that template.

Common Mistakes

1. Missing the Template Name header: Without Template Name: ... in the PHP file header, your custom template won't appear in the Template dropdown. The file header comment block is required.

2. Using incorrect file paths in get_header(): If you write get_header('landing'), WordPress looks for header-landing.php. If that file doesn't exist, it loads header.php. Always create the corresponding header file.

3. Forgetting wp_reset_postdata(): After running a custom WP_Query inside a template, always reset the post data. Without it, subsequent template tags (the_title, the_content) return the wrong data.

4. Not testing on mobile: A custom template might look perfect on desktop but break on mobile. Full-width templates especially need responsive testing — wide elements can overflow on small screens.

5. Naming conflicts with other themes: If you switch themes, templates registered in the old theme are unavailable. Bundle critical templates with a child theme or use a plugin to preserve them across theme switches.

Practice Questions

1. What is the required PHP file header for a custom page template to appear in the Template dropdown?
2. If a page has slug "services" and ID 15, which template file is used first: page-15.php, page-services.php, or page.php?
3. Why should you call wp_reset_postdata() after running a custom WP_Query in a template?

Challenge: Create a custom "Landing Page" template from scratch. It should have no header navigation, no footer widgets, no sidebar, and full-width content. Create a landing page, assign the template, and verify it renders differently from a standard page. Then add a custom background color option using the page's custom fields.

FAQ

Mini Project

Build three custom page templates:

1. Full-Width Contact Template: Includes a Google Maps embed at the top and a contact form below, no sidebar
2. Team Members Template: Displays child pages as team member cards with featured images (headshots), names, and excerpts
3. Landing Page Template: Minimal layout — no site header navigation, no footer widgets, no sidebar, full-width content area with centered text

For each template:

• Create the PHP file with the correct Template Name header
• Assign it to the appropriate page
• Verify the layout on desktop and mobile
• Check that the page slug and ID template hierarchy works

What's Next

Now that you can create custom page layouts, explore the Media Library to learn how to upload, edit, and manage images and files. Then master Image Optimization for faster page loads.

For more on site structure, see Managing Pages and Posts vs Pages.