What Is a Page Template in WordPress?

Every WordPress theme includes template files, but page templates are optional extras: a theme author adds them so you can pick a different layout for one page without touching the rest of the site. In classic themes, they’re PHP files containing custom code and functions. In block themes, they’re HTML files made entirely of block markup, and any template you create or customize in the Site Editor is saved in the database rather than in the theme’s files.

For example, a theme might ship a full-width page template, a layout with a left or right sidebar, or a page-about.php file that applies only to the page with the slug “about”. The layouts every site uses for single posts, archive pages, and 404 errors aren’t page templates: those belong to the general template system.

The page-template hierarchy

A template you assign in the editor wins, as long as it still exists. When none is assigned, WordPress works down a fixed fallback chain and uses the first file it finds:

• page-{slug}.php, which targets one page by its slug
• page-{id}.php, which targets one page by its ID
• page.php, the theme’s default layout for static pages
• singular.php, shared by pages and single posts
• index.php, the universal fallback every classic theme must include

Block themes follow the same chain with .html files. This page-specific chain is one branch of the wider template hierarchy, which picks the layout for every other kind of page the same way.

Applying a page template

Open the page in the block editor and choose a layout from the Template option in the settings sidebar. In the classic editor, the same dropdown sits under Page Attributes > Template. One caveat: any template registered with a template name is offered on every page. That’s why layouts meant for a single page are named page-{slug}.php instead, so WordPress applies them automatically.

Creating a custom page template

On a classic theme, create a PHP file whose header comment starts with “Template Name:” and add it to your theme’s folder; that one line makes the template selectable on any page. To target a single page automatically instead, name the file page-{slug}.php. On a block theme, you don’t need code at all: open the Site Editor’s Templates screen and add a new template there. Our guide to custom templates and template parts walks through both routes step by step.

Block themes vs. classic themes

Classic themes define page templates in PHP files. You can edit those files through the Theme File Editor, but direct edits to a theme’s files are overwritten the next time the theme updates. That’s why lasting changes belong in a child theme. Block themes, introduced with full site editing in WordPress 5.9 (January 2022), define page templates as HTML files of block markup in the theme’s /templates folder, as documented in the WordPress Theme Handbook. You create and edit them visually in the Site Editor (Appearance > Editor), and anything you customize there is saved to the database, where it overrules the theme’s files and survives theme updates.

Page template vs. template vs. page

The three terms are easy to mix up, so here’s the split:

• A template is any layout file in a theme, from the front page to archives to the 404 screen.
• A page template is the subset you can apply to one specific page or a group of pages, and since WordPress 4.7, to other post types too.
• A page is the content itself: the title, text, and media that a template renders.

If none of your theme’s page templates fit the layout you need, build your own, and keep the changes in a child theme or the Site Editor so a theme update can’t erase them.