WordPress Template Hierarchy: How WordPress Picks the Template File

This article is a localized edition of the Japanese original. Read the Japanese original

WordPress works out whether the requested page is a post, a page, a category archive and so on, and then looks for template files in your theme in a fixed order for that type. This order is called the Template Hierarchy. The first file found is used, and if none of them exist, index.php is used last.

Once you know this order, you can make changes such as "change the design of just this page" or "give each category its own archive layout" by adding a single file. The lists in this article follow the official WordPress documentation (Template Hierarchy in the Theme Handbook).

Main page types and lookup order

WordPress checks the files from left to right and uses the first one it finds. {slug} is replaced by the slug, {id} by the ID and {post-type} by the post type name.

For regular posts (post type post), single-{post-type}.php becomes single-post.php.

Front page and posts page

For the site's front page, front-page.php is always used if it exists. If it does not, the result depends on "Your homepage displays" under "Settings" → "Reading".

• When it shows "Your latest posts": home.php → index.php
• When it shows "A static page": the same order as for pages (page.php and so on)

The page assigned as the "Posts page" (the blog listing) uses home.php → index.php. page.php is not used.

Privacy Policy page

For the page set under "Settings" → "Privacy", privacy-policy.php is checked before the usual page order.

Non-ASCII slugs

When a slug contains non-ASCII characters (such as Japanese), WordPress 4.7 and later looks for both the raw file name and the URL-encoded file name, in that order. For example, for a page whose slug is the Japanese for "company profile", the order is page-会社概要.php, page-%e4%bc%9a%e7%a4%be%e6%a6%82%e8%a6%81.php, then page-{id}.php. Non-ASCII file names can be awkward on some servers, so using an ASCII slug or an ID-based template is usually easier.

Check which template is used

Check with the Query Monitor plugin

With the Query Monitor plugin installed, you can open it from the admin bar while logged in to see the template file used for the current page and the list of candidates WordPress looked for (the template hierarchy).

Display it yourself

During development, you can also show the template file name in the bottom-right corner of the page. WordPress stores the path of the template it uses in the global variable $template. Add the following to your child theme's functions.php, and remove it when you are done.

<?php
// Show the template name in the bottom-right corner only when an administrator is logged in
add_action( 'wp_footer', function () {
	if ( ! current_user_can( 'manage_options' ) ) {
		return;
	}
	global $template;
	printf(
		'<div style="position:fixed;bottom:0;right:0;z-index:9999;padding:6px 10px;background:#1d2327;color:#fff;font-size:12px;">%s</div>',
		esc_html( basename( $template ) )
	);
} );

Create slug-specific and ID-specific templates

To change only a specific page, put a file in your theme whose name contains that page's slug or ID.

• Page with the slug about: page-about.php
• Page with ID 42: page-42.php
• Post of post type news with the slug first-news: single-news-first-news.php

Here is an example page-about.php. Copying page.php and editing it makes it easier to keep the header and footer calls consistent.

<?php
// page-about.php: for the page whose slug is about
get_header();
?>
<main id="main" class="site-main page-about">
	<?php while ( have_posts() ) : the_post(); ?>
		<section class="about-hero">
			<h1><?php the_title(); ?></h1>
		</section>
		<section class="about-content">
			<?php the_content(); ?>
		</section>
	<?php endwhile; ?>
</main>
<?php
get_footer();

Slugs can be changed later, and if you change the slug, page-{slug}.php is no longer used. IDs do not change, but they can differ between environments (production and staging, for example).

Create a custom page template

To create a template you can pick per page in the editor, write Template Name: in the comment at the top of the file. The file name is up to you, but if it starts with page- it is easy to confuse with the slug-specific templates in the previous section, so use a different name.

<?php
/**
 * Template Name: Full Width
 * Template Post Type: page, post
 */

get_header();
?>
<main id="main" class="site-main full-width-layout">
	<?php 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; ?>
</main>
<?php
get_footer();

• The name after Template Name: appears as an option under "Template" in the editor.
• With Template Post Type:, the template can also be chosen for content other than pages (posts, in this example) in WordPress 4.7 and later. Without it, the template is available only for pages.
• WordPress reads this header from the first 8 KB of the file. Putting it in the comment at the top of the file is enough.
• Place the file directly in the theme folder or one folder level down (for example page-templates/full-width.php). Files deeper than that do not appear as options.
• Keep your own templates in a child theme so they are not lost when the parent theme is updated.

Switch templates with PHP based on conditions

To change the template based on conditions that file names cannot express (a category, login status and so on), use the template_include filter. It receives the path of the template WordPress chose, and if you return a different path, that one is used.

<?php
// Use single-premium.php for posts in the "premium" category
add_filter( 'template_include', function ( $template ) {
	if ( is_singular( 'post' ) && has_category( 'premium' ) ) {
		$premium = locate_template( 'single-premium.php' );
		if ( $premium ) {
			return $premium;
		}
	}
	return $template;
} );

locate_template() looks for the file in the child theme and then in the parent theme, and returns the full path if found or an empty string if not. Returning the original $template when the file is missing keeps you from getting a blank page if the file is deleted.

Block themes

Block themes such as Twenty Twenty-Five follow the same lookup order. The difference is that templates are HTML files in the templates folder (page.html, single.html, page-about.html and so on) instead of PHP.

• When you edit a template in "Appearance" → "Editor" (the Site Editor), the change is saved in the database and takes priority over the theme's HTML file. If editing the file does not change what you see, check whether the template has changes in the Site Editor that you have not reset.
• Templates that can be chosen in the editor are registered in customTemplates in theme.json.

Summary

• WordPress looks for templates in a fixed order for each page type and uses the first one it finds, ending with index.php
• Check the template in use with Query Monitor or by displaying $template
• To change only specific pages, use page-{slug}.php or page-{id}.php; to let editors choose, use a custom page template with Template Name:
• For conditions that file names cannot express, switch templates with the template_include filter and locate_template()
• Block themes follow the same order, with templates as HTML files in the templates folder

Related articles

• How to switch page templates by user role
• How to create an archive template with full site editing

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)