How WordPress Page Templates Actually Work

Key points:

• A WordPress® page template controls layout, while the page itself stores the content. Editing a template affects every page that uses it; editing a page affects only that page.
• Classic themes and block themes both use the template hierarchy, but classic themes rely on PHP files while block themes use editable HTML block templates managed through the Site Editor.
• WordPress® loads templates through an ordered fallback system, checking the most specific match first before falling back to more general templates.
• Use hierarchy files such as page-about.php for one specific page, named templates for reusable layouts, and custom post type templates for structured content types.
• ACF extends templates beyond layout by supplying structured content through custom fields, custom post types, taxonomies, and ACF Blocks, making templates more flexible and editor-friendly.

WordPress®¹ page templates sound simple until you realize the answer depends on the active theme, the template hierarchy, and whether the site uses a classic PHP theme, a block theme, or a page builder.

Templates control how content is displayed, but the way they are created, assigned, and customized varies significantly across modern WordPress® sites. 

This guide explains what page templates actually do, where to find them, how WordPress® chooses which template to load, and how to extend them with custom fields when a page needs more structure than the default content editor can provide.

What WordPress page templates control and what they don’t

A WordPress® page template controls the layout that surrounds content, including elements such as the header, footer, sidebar, content width, and overall page structure. The page itself holds the actual content: the text, images, blocks, and custom field values stored in the database.

A useful way to think about WordPress® is as three separate layers:

• Theme – defines the site’s overall design system, including fonts, colors, spacing, and base styles.
• Template – determines how content is arranged on a specific page or group of pages.
• Content – lives in the database and remains separate from both the theme and the template.

Understanding this separation helps avoid a common source of confusion. Editing a template changes every page that uses that template. Editing a page changes only that page’s content. If a header modification suddenly appears across multiple pages, or new content doesn’t appear where expected, the issue is often that the wrong layer was edited.

If you’re asking what the difference between a template and a page in WordPress® is:

• A page is a content record stored in the database. 
• A template is the layout file or layout definition that controls how that content is displayed on the front end.

Multiple pages can use the same template, while each page contains its own unique content.

Advanced Custom Fields (ACF®) fits into the content layer. Structured field data sits alongside the page’s blocks and content, not inside the template itself. The template decides where a field (such as project_brief) appears on the page while ACF determines what data is stored and displayed there.

Classic themes and block themes use different template systems

WordPress® still decides which template to load through an ordered set of hierarchy rules, but the files and editing workflow depend on the active theme:

• Classic themes use PHP template files. A page might load page.php, a single-use file like page-about.php, or a custom template file with a Template Name comment. Developers usually edit these files in a child theme and output page content with PHP functions such as the_content().
• Block themes use HTML template files made from block markup, usually stored in /templates, with reusable template parts such as headers and footers stored in /parts. Instead of editing PHP first, site owners can go to Appearance → Editor, customize templates visually, and save those changes to the database as block markup.

Both systems use the template hierarchy, but they do not use the same file format, editing surface, or customization location. A classic theme template is code-first. A block theme template is block-first.

For block-theme workflows that need structured field output, check this guide on how ACF makes displaying custom fields in WordPress block themes easier.

How the template hierarchy decides which file loads

The WordPress® template hierarchy is an ordered fallback system. WordPress® checks for the most specific matching template first, then falls back to broader templates until it finds one it can load.

For pages, the order usually works like this: an assigned custom template first, then page-{slug}.php, then page-{id}.php, then the default page template, and finally the theme’s general fallback template.

This is where global and single-use templates differ. A named custom template appears as a selectable option in the page editor and can be reused across many pages. A file such as page-about.php or page-42.php applies automatically to that one page through the hierarchy. Slug and ID templates do not need to be manually assigned.

For small layout differences, conditional tags can be a lighter option than creating another template. Developers can use checks such as is_page(), is_front_page(), or is_page_template() inside a shared file. However, too much conditional logic can turn one template into a maintenance problem, so separate templates are often cleaner for major layout changes.

How to create a custom page template in a classic theme

Classic themes give you two main ways to create custom page templates:

• A globally selectable named template is a PHP file with a Template Name comment header. It appears in the page editor’s Template selector and can be assigned to any page.
• A slug- or ID-targeted template is named page-{slug}.php or page-{id}.php. It loads automatically through the template hierarchy, never appears in the dropdown, and applies only to that one page.

Before adding either type, use a child theme so theme updates do not overwrite your work. The safest starting point is usually the theme’s existing page.php, because it already includes the wrappers, hooks, classes, and conventions the theme expects.

For a reusable template, create a PHP file with a header such as Template Name: Full Width Page. You can store global page templates in an organized folder like /page-templates/, but avoid naming reusable templates with the page- prefix unless they are meant to be slug-specific hierarchy files.

A basic classic template should include get_header(), the WordPress® loop, the_content(), any optional custom field output, and get_footer(). For a full-width layout, removing get_sidebar() is only part of the job; the template also needs container or class changes so the content area actually expands.

When rendering custom values, escape output appropriately, especially for user-entered content. After the file is uploaded to the active theme or child theme, it should appear in the page editor’s Template selector. ACF functions such as get_field() and the_field() belong inside the loop when outputting field data, with the ACF docs covering template tag patterns in full.

How to build and edit templates in the Site Editor

In a block theme, templates are managed visually through Appearance → Editor → Templates, where you can select an existing template or create a new one.

The key distinction is between templates and template parts:

• A template defines the full layout for a page or content type. 
• Template parts are reusable sections inside that layout, such as the Header, Footer, or Sidebar. Editing a shared Header part, for example, can affect every template that uses it.

Inside a block template, the Post Content block is what outputs the page’s actual editor content. Without it, the page may load the template structure but not display the words, images, or blocks saved on the page.

Common Site Editor changes include moving the title, removing a sidebar, adding a Cover or Group block, inserting a Query Loop, changing width and layout settings, or swapping one template part for another. Custom templates can also be registered in theme.json with customTemplates and limited to specific post types.

Site Editor changes can override the theme’s original template files without modifying those files directly. ACF Blocks, available in ACF PRO, let custom field-driven blocks live inside block-theme templates using markup such as <!-- wp:acf/your-block-name /-->, connecting visual templates with structured custom data.

Assigning a template and fixing the dropdown when it’s empty

To assign a template, open the page editor and look in the Page or Settings sidebar. The Template selector shows the layouts available for the current page. Keep in mind that the dropdown only displays templates supported by the active theme and the current post type.

If a classic-theme template is missing, check the following:

• The file is located in the active theme or child theme.
• It contains a valid Template Name comment.
• It is not accidentally named like a hierarchy file, such as page-about.php.
• It is stored in a supported location.
• The file contains no PHP syntax errors.
• The correct Template Post Type is declared when limiting templates to specific post types.

For block themes, verify that:

• The active theme supports the Site Editor.
• The template exists in the /templates directory.
• Any custom selectable template is registered correctly in theme.json.
• The editor has been refreshed after adding or registering the template.

It’s also worth checking expectations. If the theme does not include custom templates, the selector may show only the default template or provide no meaningful alternatives. In many cases, an “empty” template dropdown simply means the theme hasn’t defined additional templates yet.

Extending templates to custom post types and populating them with ACF

Page templates are not limited to standard Pages. In classic themes, a template can declare supported content types with Template Post Type, while block themes can restrict custom templates to specific post types through customTemplates.postTypes in theme.json.

It’s also important to distinguish between selectable templates and custom post type hierarchy files: 

• A selectable template can be assigned manually in the editor. 
• Files such as single-product.php, single-event.php, or their block-theme .html equivalents are hierarchy templates that WordPress® loads automatically for an entire content type.

This is where ACF becomes especially useful. Templates define the layout, while ACF provides the structured data that fills that layout. ACF can register custom post types and taxonomies, then attach field groups to pages, templates, or CPTs using location rules.

In classic themes, developers can retrieve values with functions like get_field() and output them with appropriate escaping. In block-based builds, teams can use ACF Blocks, block patterns, and custom templates to combine structured field data with editor-friendly layouts.

Common use cases include service pages with hero fields, team member profiles, event listings, resource libraries, and product-like content types. As a best practice, avoid hardcoding editor-managed content into templates. Store repeatable, structured information in fields and let the template focus on presentation. 

For a deeper walkthrough, see WordPress Custom Field Template Explained for Classic and Block Themes.

Taking your templates further

WordPress® page templates are the bridge between stored content and front-end presentation, but how they work depends on the theme system you’re using. Classic themes rely on PHP template files, while block themes use editable block-based templates. The underlying goal remains the same: controlling layout without changing the content itself.

As a practical rule, use hierarchy files when a layout should apply to one specific page, named templates when a layout should be reusable, Site Editor templates for block-theme workflows, and custom post type templates when building structured content experiences.

If you’re ready to go beyond layout and into content architecture, explore ACF’s guide to WordPress® block templates. It’s the next step toward building systems where templates don’t just control presentation, but also support structured, repeatable content models.

Build your next template with ACF and turn static layouts into flexible, editor-friendly content systems powered by custom fields, custom post types, taxonomies, and ACF Blocks.

WordPress page templates FAQs

How can I tell which template a page is currently using?

In classic themes, one quick clue is the <body> class output. You may see classes such as page-template-default, page-template, or a sanitized version of the template file name, such as page-template-tpl-projects-php. However, body classes are not definitive. A hierarchy file like page-about.php or page-42.php may still display page-template-default, even though WordPress® loaded a more specific template.

For developer-level verification, get_page_template() returns the PHP template path WordPress® is using, while is_page_template( 'tpl-projects.php' ) checks whether a specific custom template is assigned. If the template lives in a folder, include the folder path in the check.

In block themes, the page editor’s Template selector shows the assigned template. Keep in mind that the rendered version may come from the theme’s /templates directory or from a Site Editor customization stored in the database.

How do page builders interact with the native template system?

Page builders can either work alongside WordPress® templates or replace large parts of the template system entirely.

In a basic page-building workflow, the builder renders its content inside the active theme’s template or a builder-provided layout such as Canvas or Full Width. In this scenario, the selected template still affects elements like the header, footer, sidebar, and content width.

In a full theme-builder workflow, the builder may take control of headers, footers, single templates, archive templates, product templates, and even 404 pages. The layout data is often stored outside traditional template files, such as in post metadata, custom post types, builder templates, or plugin-specific settings.

The best approach is to establish clear ownership. Let the theme, Site Editor, or page builder control a given layout layer, but avoid having all three compete for control of the same page.