As discussed, template files are modular, reusable files, used to generate the web pages on your WordPress site. Some template files (such as the header and footer template) are used on all of your site’s pages, while others are used only under specific conditions.
This article explains how WordPress determines which template file(s) to use on individual pages. If you want to customize an existing WordPress theme it will help you decide which template file needs to be edited.
The Template File Hierarchy
Overview
WordPress uses the query string to decide which template or set of templates should be used to display the page. The query string is information that is contained in the link to each part of your website.
Put simply, WordPress searches down through the template hierarchy until it finds a matching template file. To determine which template file to use, WordPress:
- Matches every query string to a query type to decide which page is being requested (for example, a search page, a category page, etc);
- Selects the template in the order determined by the template hierarchy;
- Looks for template files with specific names in the current theme’s directory and uses the first matching template file as specified by the hierarchy.
With the exception of the basic index.php
template file, you can choose whether you want to implement a particular template file or not.
If WordPress cannot find a template file with a matching name, it will skip to the next file in the hierarchy. If WordPress cannot find any matching template file, the theme’s index.php
file will be used.
When you are using a child theme, any file you add to your child theme will over-ride the same file in the parent theme. For example, both themes contain the same template category.php
, then child theme’s template is used.
If a child theme contains the specific template such as category-unicorns.php
and the parent theme contains lower prioritized template such as category.php
, then child theme’s category-unicorns.php
is used.
Contrary, if a child theme contains general template only such as category.php
and the parent theme contains the specific one such as category-unicorns.php
, then parent’s template category-unicorns.php
is used.
Examples
If your blog is at http://example.com/blog/
and a visitor clicks on a link to a category page such as http://example.com/blog/category/your-cat/
, WordPress looks for a template file in the current theme’s directory that matches the category’s ID to generate the correct page. More specifically, WordPress follows this procedure:
- Looks for a template file in the current theme’s directory that matches the category’s slug. If the category slug is “unicorns,” then WordPress looks for a template file named
category-unicorns.php
. - If
category-unicorns.php
is missing and the category’s ID is 4, WordPress looks for a template file namedcategory-4.php
. - If
category-4.php
is missing, WordPress will look for a generic category template file,category.php
. - If
category.php
does not exist, WordPress will look for a generic archive template,archive.php
. - If
archive.php
is also missing, WordPress will fall back to the main theme template file,index.php
.
Visual Overview
The following diagram shows which template files are called to generate a WordPress page based on the WordPress template hierarchy.
The Template Hierarchy In Detail
While the template hierarchy is easier to understand as a diagram, the following sections describe the order in which template files are called by WordPress for a number of query types.
Home Page display
By default, WordPress sets your site’s home page to display your latest blog posts. This page is called the blog posts index. You can also set your blog posts to display on a separate static page. The template file home.php
is used to render the blog posts index, whether it is being used as the front page or on separate static page. If home.php
does not exist, WordPress will use index.php
.
home.php
index.php
front-page.php
exists, it will override the home.php
template.Front Page display
The front-page.php
template file is used to render your site’s front page, whether the front page displays the blog posts index (mentioned above) or a static page. The front page template takes precedence over the blog posts index (home.php
) template. If the front-page.php
file does not exist, WordPress will either use the home.php
or page.php
files depending on the setup in Settings Reading. If neither of those files exist, it will use the index.php
file.
front-page.php
– Used for both “your latest posts” or “a static page” as set in the front page displays section of Settings Reading.home.php
– If WordPress cannot findfront-page.php
and “your latest posts” is set in the front page displays section, it will look forhome.php
. Additionally, WordPress will look for this file when the posts page is set in the front page displays section.page.php
– When “front page” is set in the front page displays section.index.php
– When “your latest posts” is set in the front page displays section buthome.php
does not exist or when front page is set butpage.php
does not exist.
As you can see, there are a lot of rules to what path WordPress takes. Using the chart above is the best way to determine what WordPress will display.
Privacy Policy Page display
The privacy-policy.php
template file is used to render your site’s Privacy Policy page. The Privacy Policy page template takes precedence over the static page (page.php
) template. If the privacy-policy.php
file does not exist, WordPress will either use the page.php
or singular.php
files depending on the available templates. If neither of those files exist, it will use the index.php
file.
-
privacy-policy.php
– Used for the Privacy Policy page set in the Change your Privacy Policy page section of Settings Privacy. custom template file
– The page template assigned to the page. Seeget_page_templates()
.page-{slug}.php
– If the page slug isprivacy
, WordPress will look to usepage-privacy.php
.page-{id}.php
– If the page ID is 6, WordPress will look to usepage-6.php
.page.php
singular.php
index.php
Single Post
The single post template file is used to render a single post. WordPress uses the following path:
single-{post-type}-{slug}.php
– (Since 4.4) First, WordPress looks for a template for the specific post. For example, if post type isproduct
and the post slug isdmc-12
, WordPress would look forsingle-product-dmc-12.php
.single-{post-type}.php
– If the post type isproduct
, WordPress would look forsingle-product.php
.single.php
– WordPress then falls back tosingle.php
.singular.php
– Then it falls back tosingular.php
.index.php
– Finally, as mentioned above, WordPress ultimately falls back toindex.php
.
Single Page
The template file used to render a static page (page
post-type). Note that unlike other post-types, page
is special to WordPress and uses the following path:
custom template file
– The page template assigned to the page. Seeget_page_templates()
.page-{slug}.php
– If the page slug isrecent-news
, WordPress will look to usepage-recent-news.php
.page-{id}.php
– If the page ID is 6, WordPress will look to usepage-6.php
.page.php
singular.php
index.php
Category
Rendering category archive index pages uses the following path in WordPress:
category-{slug}.php
– If the category’s slug isnews
, WordPress will look forcategory-news.php
.category-{id}.php
– If the category’s ID is6
, WordPress will look forcategory-6.php
.category.php
archive.php
index.php
Tag
To display a tag archive index page, WordPress uses the following path:
tag-{slug}.php
– If the tag’s slug issometag
, WordPress will look fortag-sometag.php
.tag-{id}.php
– If the tag’s ID is6
, WordPress will look fortag-6.php
.tag.php
archive.php
index.php
Custom Taxonomies
Custom taxonomies use a slightly different template file path:
taxonomy-{taxonomy}-{term}.php
– If the taxonomy issometax
, and taxonomy’s term issometerm
, WordPress will look fortaxonomy-sometax-someterm.php.
In the case of post formats, the taxonomy is ‘post_format’ and the terms are ‘post-format-{format}. i.e.taxonomy-post_format-post-format-link.php
for the link post format.taxonomy-{taxonomy}.php
– If the taxonomy weresometax
, WordPress would look fortaxonomy-sometax.php
.taxonomy.php
archive.php
index.php
Custom Post Types
Custom Post Types use the following path to render the appropriate archive index page.
archive-{post_type}.php
– If the post type isproduct
, WordPress will look forarchive-product.php
.archive.php
index.php
(For rendering a single post type template, refer to the single post display section above.)
Author display
Based on the above examples, rendering author archive index pages is fairly explanatory:
author-{nicename}.php
– If the author’s nice name ismatt
, WordPress will look forauthor-matt.php
.author-{id}.php
– If the author’s ID were6
, WordPress will look forauthor-6.php
.author.php
archive.php
index.php
Date
Date-based archive index pages are rendered as you would expect:
date.php
archive.php
index.php
Search Result
Search results follow the same pattern as other template types:
search.php
index.php
404 (Not Found)
Likewise, 404 template files are called in this order:
404.php
index.php
Attachment
Rendering an attachment page (attachment
post-type) uses the following path:
{MIME-type}.php
– can be any MIME type (For example:image.php
,video.php
,pdf.php
). Fortext/plain
, the following path is used (in order):text-plain.php
plain.php
text.php
attachment.php
single-attachment-{slug}.php
– For example, if the attachment slug isholiday
, WordPress would look forsingle-attachment-holiday.php
.single-attachment.php
single.php
singular.php
index.php
As of WordPress 6.4, attachment pages are no longer enabled by default on new installations. Users can enable them with a plugin, so it is still good practice to test your theme and ensure it properly displays content when viewing an attachment page.
Embeds
The embed template file is used to render a post which is being embedded. Since 4.5, WordPress uses the following path:
embed-{post-type}-{post_format}.php
– First, WordPress looks for a template for the specific post. For example, if its post type ispost
and it has the audio format, WordPress would look forembed-post-audio.php
.embed-{post-type}.php
– If the post type isproduct
, WordPress would look forembed-product.php
.embed.php
– WordPress then falls back to embed.php
.- Finally, WordPress ultimately falls back to its own
wp-includes/theme-compat/embed.php
template.
Non-ASCII Character Handling
Since WordPress 4.7, any dynamic part of a template name which includes non-ASCII characters in its name actually supports both the un-encoded and the encoded form, in that order. You can choose which to use.
Here’s the page template hierarchy for a page named “Hello World 😀” with an ID of 6
:
page-hello-world-😀.php
page-hello-world-%f0%9f%98%80.php
page-6.php
page.php
singular.php
The same behaviour applies to post slugs, term names, and author nicenames.
Filter Hierarchy
The WordPress template system lets you filter the hierarchy. This means that you can insert and change things at specific points of the hierarchy. The filter (located in the get_query_template()
function) uses this filter name: "{$type}_template"
where $type
is the template type.
Here is a list of all available filters in the template hierarchy:
embed_template
404_template
search_template
frontpage_template
home_template
privacypolicy_template
taxonomy_template
attachment_template
single_template
page_template
singular_template
category_template
tag_template
author_template
date_template
archive_template
index_template
Example
For example, let’s take the default author hierarchy:
author-{nicename}.php
author-{id}.php
author.php
To add author-{role}.php
before author.php
, we can manipulate the actual hierarchy using the ‘author_template’ template type. This allows a request for /author/username where username has the role of editor to display using author-editor.php if present in the current themes directory.
function author_role_template( $templates = '' ) {
$author = get_queried_object();
$role = $author->roles[0];
if ( ! is_array( $templates ) && ! empty( $templates ) ) {
$templates = locate_template( array( "author-$role.php", $templates ), false );
} elseif ( empty( $templates ) ) {
$templates = locate_template( "author-$role.php", false );
} else {
$new_template = locate_template( array( "author-$role.php" ) );
if ( ! empty( $new_template ) ) {
array_unshift( $templates, $new_template );
}
}
return $templates;
}
add_filter( 'author_template', 'author_role_template' );
Changelog:
- Updated 2022-02-15. Added a notice explaining that the template hierarchy is the same for classic and block themes, but that the examples uses .php files and block themes use .html files.