Developer · Guide
How to Create a Custom Page Template

Short answer
To create a custom page template in a classic theme, copy page.php into a new file in your theme, add a Template Name comment at the top, upload it to the theme folder or a first-level subfolder, then pick it in the page editor under Page Attributes and Template. In a block theme, build the template with blocks in the Site Editor instead.
Key takeaways
- A custom page template changes the layout of one page or a group of pages.
- WordPress checks the assigned template first, then page-slug, page-id, page.php, singular.php, and index.php.
- Page templates have supported all post types since WordPress 4.7.
- A global template needs a Template Name header and must not use the page- file prefix.
- Block themes use HTML templates built in the Site Editor, not PHP template files.
What is a custom page template?
A custom page template is a theme file that changes the layout of one page or a group of pages.
Page templates are a specific type of template file that can be applied to a specific page or groups of pages. Developer.WordPress.org states that page templates change the look and feel of a page, such as a full-width layout or a two-column layout with a sidebar (checked November 2026).
A template can show different content from the default page layout. Developer.WordPress.org states that page templates display dynamic content such as posts, news updates, calendar events, and media files (checked November 2026).
Use a page template when one page needs a layout the rest of the site does not use. A guide on posts vs pages in WordPress explains when to use a page at all, before you design its layout.
How do custom, specialized, and default templates differ?
A custom template is picked by the editor, a specialized template is picked by page slug or id, and the default template applies to all other pages.
Developer.WordPress.org states that a page template with a template name can be picked by any user editing a page, while a specialized template targets one page by its slug or id (checked November 2026).
WordPress checks templates in a fixed order when it renders a page. Developer.WordPress.org lists that order as the assigned custom template first, then page-slug, then page-id, then page.php, then singular.php, and finally index.php (checked November 2026).
| Template kind | How WordPress picks it | Best use |
|---|---|---|
| Custom template | Editor picks it in Page Attributes | Full-width or landing layout for many pages |
| Specialized template | File name matches the page slug or id | One page, such as About, with its own layout |
| Default page.php | No other template matches | Every other page on the site |
| singular.php | page.php is missing | Fallback for single posts and pages |
| index.php | Nothing else matches | Last fallback for all content |
A specialized template named page-about.php only affects a page with the slug about. Developer.WordPress.org states that this file is more specific than page.php or index.php because it targets one page (checked November 2026).
A custom template with a name is offered to every page editor, so name it for what it does, not for one page. Developer.WordPress.org warns that naming a template after one page still makes it available to all pages (checked November 2026).
What do you need before you start?
You need a classic theme, a child theme for your changes, and a copy of the theme page.php file.
Page templates with PHP code only work in classic themes. Block themes store templates as HTML files instead, and the block theme section later in this guide covers that route.
Work in a child theme so a parent theme update does not wipe your template file. If you edit the parent theme directly, your template disappears at the next update.
Copy the theme page.php file as your starting point. Developer.WordPress.org states that copying page.php is a quick, safe way to start, since you begin with the HTML structure of your other pages (checked November 2026).
Keep a backup of the site before you add theme files. A broken template file can show errors on the pages that use it, so test on a staging copy first when you can.
How do you create a global page template?
Add a Template Name comment at the top of a PHP file in your theme, then upload it to the theme folder.
Create a new file in the theme folder, such as page-templates/full-width.php, and put this header at the top, followed by the copied page.php code.
Template Name: Full Width Page
Developer.WordPress.org states that WordPress can read page templates stored in the theme root folder or in a first-level subdirectory, and that page-templates is a common convention (checked November 2026).
The header is a PHP comment, and PHP.net documents the comment styles PHP supports, including the multi-line form used in the header (checked November 2026).
Nested folders do not work for page templates. Developer.WordPress.org states that nested subdirectories, such as pages/templates, are not supported for page templates (checked November 2026).
Do not start the file name with page- for a global template. Developer.WordPress.org warns that WordPress reads a page- prefix as a specialized template meant for one page only (checked November 2026).
Pick a name that states what the template does, such as Full Width Page, since that name is what editors see. Developer.WordPress.org notes that the template list has a maximum width of 250 pixels, so long names may be cut off (checked November 2026).
How do you create a template for one specific page?
Copy page.php and rename it page-slug.php or page-id.php, with no Template Name header needed.
To target one page, copy your page.php file and rename it with the page slug or id. Developer.WordPress.org gives the example of an About page with slug about and id 6, which WordPress renders from page-about.php or page-6.php (checked November 2026).
Specialized templates must sit in the theme root folder, not in a subfolder. Developer.WordPress.org states that a specialized page template file cannot be stored in a subfolder, and in a child theme it cannot sit in the parent theme folder (checked November 2026).
WordPress finds the file on its own, so you do not pick it in the editor. The page uses it each time a visitor opens that page, until you rename or delete the file.
Use this route when the layout belongs to one page only. If two pages need the same layout, use a global template with a Template Name header instead, so both pages can pick it.
A guide on how to edit the header in a block theme covers header changes when your theme uses blocks rather than PHP templates.
How do you assign a template to a page?
Open the page in the editor, find the Template list under Page Attributes, pick the template, and save.
After you upload the template file, open the page from Pages in the dashboard. Developer.WordPress.org states that the list of available templates sits at Pages, Add New, Attributes, Template in the editor (checked November 2026).
Pick the template name from the list and save the page. The front end then renders that page with your template file instead of page.php.
WordPress records the choice in the database. Developer.WordPress.org states that the assigned file name is stored in a custom field named _wp_page_template in the wp_postmeta table (checked November 2026).
If the template does not appear in the list, check that the file is in the theme root or a first-level folder, that the header comment is at the very top, and that the theme active on the site is the one holding the file.
How do you limit a template to certain post types?
Add a Template Post Type line under the Template Name header, listing the post types the template supports.
Page templates have supported all post types since WordPress 4.7. Developer.WordPress.org states that as of WordPress 4.7, page templates support all post types, and the Template Post Type line picks which ones (checked November 2026).
Template Name: Full-width layout
Template Post Type: post, page, event
Developer.WordPress.org states that when at least one template exists for a post type, the Post Attributes box shows in the editor without any extra post type support (checked November 2026).
Without the Template Post Type line, a custom template is offered for pages only. Add the line when you want the same layout on posts or on a custom post type such as an event type.
Check the template in each post type editor after you add the line. The template should appear in the Template list for the listed types and stay hidden for the rest.
How do you build a template in a block theme?
Build it in the Site Editor with blocks, since block themes use HTML template files instead of PHP template tags.
In block themes, templates are HTML files that hold block markup. Developer.WordPress.org states that in modern block themes, templates are HTML files with block markup, and blocks are used instead of template tags (checked November 2026).
Open Appearance, then Editor, then Templates to work with templates in the dashboard. WordPress.org states that the Template Editor lets you edit and create templates using blocks, and that those templates control the layout of posts, pages, or page types (checked November 2026).
WordPress.org states that the Site Editor is only available when a block theme is active, and that it lets you design the whole site, including header, footer, and everything between, with blocks (checked November 2026).
Learn WordPress states that a template provides the structure for how a page is displayed, and that you can create a custom template and assign it to a page or post from the Site Editor (checked November 2026).
WordPress.org states that changes you make to a template in the editor update the blocks on all pages and posts that use it, and that those changes take priority over the theme bundled template files (checked November 2026).
A guide on block themes vs classic themes explains the split between the two theme types, so you can tell which route your site needs.
How do you check the template works?
Open the page on the front end, confirm the layout changed, and confirm other pages stayed the same.
Visit the page in a private browser window and check the layout, sidebar, and content width. A full-width template should drop the sidebar, and a two-column template should show it.
Check a second page that still uses the default template. If it changed too, you edited page.php itself instead of a copy, or you assigned the new template to that page as well.
WordPress offers functions to confirm which template rendered a page. Developer.WordPress.org lists get_page_template, which returns the path of the template used, and is_page_template, which returns true or false for a custom template (checked November 2026).
A guide on how to use theme.json covers the style settings that shape how a template looks once the layout file is right.
What mistakes should you avoid?
Avoid editing the parent theme, using the page- prefix for a global template, and naming a template after one page.
Editing the parent theme means your template is lost at the next theme update. Put the file in a child theme and keep the parent untouched.
Using page- as a prefix turns a global template into a specialized one. Developer.WordPress.org states that WordPress reads the page- prefix as a specialized template for one page, so a global template needs a different prefix (checked November 2026).
Naming a template after one page, such as About Template, still offers it to every page editor. Pick a name that states the layout, such as Full Width Page, so editors pick it for the right reason.
Avoid adding a Template Post Type line that lists types the template code cannot render. Test the template on each listed post type before you hand the site to editors.
Frequently asked questions
Is a page template the same in a block theme and a classic theme?
A page template file is a PHP file in a classic theme, and it works by its Template Name header and file name. A block theme template is an HTML file built from blocks in the Site Editor, with no PHP template tags. The two kinds are not interchangeable, so check which theme type your site uses first.
Can I use a page-slug file to offer a layout to any page?
No. A file named page-about.php only renders the page with the slug about, and WordPress picks it on its own. To offer a layout to editors, give the file a Template Name header and a name that does not start with page-, then pick it in the page editor.
Why does my new template not show in the Template list?
The most likely cause is the file location or the header. The file must sit in the theme root or a first-level folder, the Template Name comment must be at the very top, and the active theme must be the one holding the file. Nested folders are not read as page templates.
Can a page template be used on posts or custom post types?
Yes. Add a Template Post Type line under the Template Name header, listing the post types, such as post, page, and event. This has worked since WordPress 4.7. Without that line, the template is offered for pages only.
Does a page template survive a theme change?
Yes, but only while that theme stays active. The template file lives in the theme folder, so switching themes drops it. If the layout must survive a theme change, rebuild it as a plugin feature or as content that does not depend on the theme files.
Sources
- Page Templates WordPress Developer Resources
- Introduction to Templates WordPress Developer Resources
- Template Files WordPress Developer Resources
- Template Editor WordPress.org
- Site Editor WordPress.org
- Using page templates Learn WordPress
- Comments PHP.net
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.


