{"id":162527,"date":"2017-02-09T13:00:38","date_gmt":"2017-02-09T13:00:38","guid":{"rendered":"https:\/\/premium.wpmudev.org\/blog\/?p=162527"},"modified":"2022-03-02T04:49:41","modified_gmt":"2022-03-02T04:49:41","slug":"guide-wordpress-template-hierarchy","status":"publish","type":"post","link":"https:\/\/wpmudev.com\/blog\/guide-wordpress-template-hierarchy\/","title":{"rendered":"A Straightforward Guide to the WordPress Template Hierarchy"},"content":{"rendered":"<p>If you&#8217;re building your own themes for WordPress, or using a child theme to customize a third party theme, at some point you&#8217;ll come across the template hierarchy.<\/p>\n<p>It&#8217;s a brilliant system that dictates how WordPress chooses which template file to use for different types of content. It takes into account content types (e.g. posts, pages, attachment and custom post types), taxonomies (e.g. in category, tag and custom taxonomy archives) and even lets you create bespoke templates for specific pages.<\/p>\n<p>But it can be confusing. When faced with an archive for a taxonomy that applies to a post type, for example, which template should you use? And how do templates for single posts work?<\/p>\n<p>In this post I&#8217;ll walk you through the template hierarchy and explain how it works with some worked examples. By the time you&#8217;ve read through this you should be able to create theme template files like a pro!<\/p>\n<div  class=\"wpdui-pic-large   \" >\n<figure class=\"wp-caption aligncenter\" data-caption=\"true\"><img loading=\"lazy\" decoding=\"async\" class=\"attachment-1364x1364 size-1364x1364\" src=\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2017\/02\/wphierarchy.png\" alt=\"The wphierarchy site is a great refresher on the template hierarchy.\" width=\"1364\" height=\"584\" \/><figcaption class=\"wp-caption-text\">The wphierarchy site is a great refresher on the template hierarchy.<\/figcaption><\/figure>\n<\/div>\n<p><em>Note: my favorite resource on the template hierarchy is <a href=\"https:\/\/wphierarchy.com\/\" target=\"_blank\">wphierarchy<\/a>, which has a clear\u00a0interactive\u00a0diagram.<\/em><\/p>\n<p>Continue reading, or jump ahead using these links:<\/p>\n<ul>\n<li><a href=\"#wordpress-template-hierarchy\">The WordPress Template Hierarchy: Types of Templates<\/a><\/li>\n<li><a href=\"#how-wordpress-chooses-a-template-file\">How WordPress Chooses a Template File<\/a><\/li>\n<li><a href=\"#example\">A Worked Example<\/a><\/li>\n<li><a href=\"#include-files\">Include Files<\/a><\/li>\n<li><a href=\"#template-files-and-child-themes\">Template Files and Child Themes<\/a><\/li>\n<\/ul>\n<h2 id=\"wordpress-template-hierarchy\">The WordPress Template Hierarchy: Types of Templates<\/h2>\n<p>The template hierarchy dictates how WordPress deals with five\u00a0main page types:<\/p>\n<ul>\n<li>There are three\u00a0template files that are more general. The fallback template file is <em>index.php<\/em>. This is used if WordPress can&#8217;t find anything else for the specific content type.\u00a0It should, therefore, work correctly for archive pages, single posts and single pages (as well as all other content types). A theme has to have an <em>index.php<\/em> file to work; it could, in theory, have just this file and the stylesheet. The other general template files are\u00a0<em>404.php<\/em> for errors and <em>search.php<\/em> for search results.<\/li>\n<li>Templates for specific archive displays, like\u00a0category and taxonomy archives, let you display different content for different listings. For example you could use alternative archive template files if one post type has custom fields you want to display, if you want to alter\u00a0the loop or if you want to add extra content or widget areas.<\/li>\n<li>Page templates help you display different content on different static pages (for example if you want to display a sidebar on some pages but not all). You can then choose which template a given page uses via the admin screens.<\/li>\n<li>Single post templates, including custom post type templates, let you display different content for different post types, for example if you want to use the loop differently (e.g. displaying different metadata).<\/li>\n<li>Includes, such as <em>header.php<\/em>, <em>sidebar.php<\/em> and <em>footer.php<\/em>, can be created for different areas for the site in place of or as well as a template file, to display different widgets or content in these areas of the site. They don\u2019t just have to be for headers, footers, and sidebars though \u2013 you can use an include anywhere you want to save writing the same piece of code into every template file. A common example is the WordPress Loop.<\/li>\n<\/ul>\n<div  class=\"wpdui-pic-regular  \">\n<figure class=\"wp-caption aligncenter\" data-caption=\"true\"><img loading=\"lazy\" decoding=\"async\" class=\"attachment-670x670 size-670x670\" src=\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2017\/02\/page-template-chooser.png\" alt=\"page attributes meta box in the wordpress page editing screen\" width=\"670\" height=\"568\" \/><figcaption class=\"wp-caption-text\">On my website I&#8217;ve set up a number of page templates which I can select in the page editing screen<\/figcaption><\/figure>\n<\/div>\n<h2 id=\"how-wordpress-chooses-a-template-file\">How WordPress Chooses a Template File<\/h2>\n<p>When WordPress opens a page on your site it checks what content type is being displayed and then chooses the correct\u00a0template file accordingly.<\/p>\n<p>For static pages:<\/p>\n<ul>\n<li><em>singular.php<\/em> overrides\u00a0<em>index.php<\/em>, and then <em>page.php<\/em>\u00a0overrides both.<\/li>\n<li><em>page-$slug.php<\/em> or <em>page-$ID.php<\/em> override\u00a0<em>page.php<\/em> when a page with the correct slug or ID is being displayed<\/li>\n<li><em>front-page.php<\/em>\u00a0beats <em>index.php<\/em> and <em>page.php<\/em> when the home page is viewed.<\/li>\n<li>A custom template page, such as\u00a0<em>page-without-sidebar.php<\/em>, when selected through the page\u2019s admin panel, beats\u00a0<em>page.php<\/em>, <em>home.php<\/em>, <em>page-$slug.php<\/em> and <em>page-$ID.php<\/em>.<\/li>\n<\/ul>\n<p>For individual posts and attachments:<\/p>\n<ul>\n<li><em>singlular.php<\/em>\u00a0overrides <em>index.php<\/em>, and <em>single.php<\/em> beats both.<\/li>\n<li><em>single-post.php<\/em>\u00a0overrides <em>single.php<\/em> when a single post is being viewed (as against an attachment or a custom post type).<\/li>\n<li><em>single-$posttype.php<\/em>\u00a0beats\u00a0<em>single.php<\/em> when displaying a single post of a given post type.<\/li>\n<li><em>single-$posttype-$slug.php<\/em> beats <em>single-$posttype.php<\/em> for a post with the given slug.<\/li>\n<li><em>attachment.php<\/em>\u00a0overrides <em>single.php<\/em> when an attachment is viewed.<\/li>\n<li>A custom MIME type page (<em>$mimetype.php<\/em>) beats\u00a0<em>attachment.php<\/em> when attachments of a given MIME type are viewed. For example, you could use <em>image.php<\/em>, <em>video.php<\/em>, or any accepted MIME type.<\/li>\n<\/ul>\n<p>For archives:<\/p>\n<ul>\n<li><em>home.php<\/em> beats <em>index.php<\/em> for the home page or\u00a0the main blog. If\u00a0the home page is the main blog page, then <em>front-page.php<\/em> beats both of these.<\/li>\n<li><em>archive.php<\/em> beats\u00a0<em>index.php<\/em> when a category, tag, date, or author listing is viewed.<\/li>\n<li><em>category.php<\/em> overrides archive.php when a specific category listing is viewed. A <em>category-$slug.php<\/em> or <em>category-$ID.php<\/em> template\u00a0override\u00a0<em>category.php<\/em> when displaying posts from the relevant category ID or slug.<\/li>\n<li><em>tag.php<\/em> overrides <em>archive.php<\/em> when a tag listing is viewed. A <em>tag-$slug.php<\/em> or <em>tag-$ID.php<\/em> file override\u00a0<em>tag.php<\/em>.<\/li>\n<li><em>author.php<\/em> overrides <em>archive.php<\/em> when the list of posts by an author is viewed, which in turn is trumped by <em>author-$ID.php<\/em> and <em>author-$nicename.php<\/em>.<\/li>\n<li><em>archive-$posttype.php<\/em> beats\u00a0<em>archive.php<\/em> when listings for a given post type are being viewed.<\/li>\n<li><em>date.php<\/em> overrides <em>archive.php<\/em> when a list of posts for a given date is viewed.<\/li>\n<li><em>taxonomy.php<\/em> overrides <em>archive.php<\/em> when viewing a taxonomy archive. For a specific taxonomy, <em>taxonomy-$taxonomy.php<\/em> will also beat that (where <em>$taxonomy<\/em> is the taxonomy slug), and for a term in the taxonomy, <em>taxonomy-$taxonoomy-$term.php<\/em> will beat all of these.<\/li>\n<\/ul>\n<p>In addition:<\/p>\n<ul>\n<li><em>search.php<\/em> trumps <em>index.php<\/em> when the results from a search are viewed. You might expect a search to use an archive template but it doesn&#8217;t: it either uses <em>index.php<\/em> or <em>search.php<\/em> if that exists.<\/li>\n<li><em>404.php<\/em>\u00a0beats everything else when a URL is displayed for which WordPress can find no content. You can use this to display some custom content for 404 pages, such as an error message and search box.<\/li>\n<li><em>index.ph<\/em>p is essential for the theme to work as WordPress will fall back to it when displaying content not accounted for by any of the other templates you\u2019ve set up.<\/li>\n<\/ul>\n<h2 id=\"example\">A Worked Example<\/h2>\n<p>Let&#8217;s imagine my site has a number of single pages, a front page with static content, plenty of archives, a post type of <em>product<\/em> and a taxonomy of <em>productcat<\/em>.<\/p>\n<p>My theme has these template files:<\/p>\n<ul>\n<li><em>index.php<\/em><\/li>\n<li><em>front-page.php<\/em><\/li>\n<li><em>page.php<\/em><\/li>\n<li><em>mypagetemplate.php<\/em><\/li>\n<li><em>single.php<\/em><\/li>\n<li><em>archive.php<\/em><\/li>\n<li><em>category.php<\/em><\/li>\n<li><em>taxonomy.php<\/em><\/li>\n<li><em>taxonomy-productcat-featured.php<\/em><\/li>\n<li><em>404.php<\/em><\/li>\n<li><em>search.php<\/em><\/li>\n<\/ul>\n<p>Which file do you think WordPress would use for these pages in my site?<\/p>\n<ul>\n<li>The home page (a static page)<\/li>\n<li>A static page<\/li>\n<li>A single post<\/li>\n<li>A product<\/li>\n<li>A product with\u00a0the <em>featured<\/em> term in the <em>productcat<\/em> taxonomy<\/li>\n<li>An error page<\/li>\n<li>A search page<\/li>\n<li>A category archive<\/li>\n<li>A tag archive.<\/li>\n<\/ul>\n<p>See if you can work out from my guide above which template file my site would use for each of those pages. No checking below!!<\/p>\n<p>Here are the answers:<\/p>\n<ul>\n<li>The home page: <em>front-page.php<\/em><\/li>\n<li>A static page: <em>page.php<\/em> (or <em>mypagetemplate.php<\/em> if I select that in the page admin screen)<\/li>\n<li>A single post: <em>single.php<\/em><\/li>\n<li>A product: <em>single.php<\/em><\/li>\n<li>A product\u00a0with\u00a0the\u00a0<em>featured<\/em>\u00a0term in the\u00a0<em>productcat<\/em>\u00a0taxonomy:\u00a0<em>taxonomy-productcat-featured.php<\/em><\/li>\n<li>An error page: <em>404.php<\/em><\/li>\n<li>A search page: <em>search.php<\/em><\/li>\n<li>A category archive: <em>category.php<\/em><\/li>\n<li>A tag archive: <em>archive.php<\/em><\/li>\n<\/ul>\n<p>Did you get them all right? If not, take some time to work through each and familiarise yourself with how WordPress would work through the template hierarchy.<\/p>\n<h2 id=\"include-files\">Include Files<\/h2>\n<p>As well as\u00a0the template files, WordPress uses a number of includes, which are used for content which will be inserted\u00a0into a template. The most common includes are <em>header.php<\/em>, <em>sidebar.php<\/em> and <em>footer.php<\/em>, all of which can have multiple versions such as <em>header-home.php<\/em>, <em>sidebar-$posttype.php<\/em> or whatever\u2019s needed for your site.<\/p>\n<p>To call the generic header in your template file, use <a href=\"https:\/\/codex.wordpress.org\/Function_Reference\/get_header\" target=\"_blank\"><code>get_header()<\/code><\/a>:<\/p>\n<p><span style=\"font-weight: 400;\"><div class=\"gist\" data-gist=\"600841201c96ce04abc049d93428a67d\" data-gist-file=\"get header\"><a class=\"loading\" href=\"https:\/\/gist.github.com\/600841201c96ce04abc049d93428a67d.js?file=get+header\">Loading gist 600841201c96ce04abc049d93428a67d<\/a><div class=\"gist-consent-notice\" style=\"display:none\"><p>Please <a href=\"javascript:Cookiebot.renew()\">update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div><\/span><\/p>\n<p>If you want to create a specific header include file for one of the content types on your theme (e.g. the home page), you could create a file called <em>header-home.php<\/em> and then call it like this:<\/p>\n<p><span style=\"font-weight: 400;\"><div class=\"gist\" data-gist=\"99da99a9fe2de6d472906d90f169b133\" data-gist-file=\"get header home\"><a class=\"loading\" href=\"https:\/\/gist.github.com\/99da99a9fe2de6d472906d90f169b133.js?file=get+header+home\">Loading gist 99da99a9fe2de6d472906d90f169b133<\/a><div class=\"gist-consent-notice\" style=\"display:none\"><p>Please <a href=\"javascript:Cookiebot.renew()\">update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div><\/span><\/p>\n<p>This would call the <em>header-home.php<\/em> file and output its contents where you place it in the template file (which should be at the top). You would either use this in place of the standard include in the relevant template file (in this case <em>home.php<\/em>), or you could use it in a conditional function, as below:<\/p>\n<p><span style=\"font-weight: 400;\"><div class=\"gist\" data-gist=\"86b0f8feea9efb233c2fe3e41a97127f\" data-gist-file=\"header home conditional\"><a class=\"loading\" href=\"https:\/\/gist.github.com\/86b0f8feea9efb233c2fe3e41a97127f.js?file=header+home+conditional\">Loading gist 86b0f8feea9efb233c2fe3e41a97127f<\/a><div class=\"gist-consent-notice\" style=\"display:none\"><p>Please <a href=\"javascript:Cookiebot.renew()\">update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div><\/span><\/p>\n<p>You can use this to call one of multiple includes depending on what part of the site the user is in.<\/p>\n<p>As well as the header, sidebar and footer includes, WordPress makes use of some other standard includes:<\/p>\n<ul>\n<li><a href=\"https:\/\/developer.wordpress.org\/reference\/functions\/get_search_form\/\" target=\"_blank\"><code>get_search_form()<\/code><\/a> fetches the <em>searchform.php<\/em> file from your theme \u2013 if one doesn\u2019t exist, WordPress will generate the search form<\/li>\n<li><a href=\"https:\/\/developer.wordpress.org\/reference\/functions\/comments_template\/\" target=\"_blank\"><code>comments_template()<\/code><\/a> fetches the <em>comments.php<\/em> file from your theme \u2013 if there isn\u2019t one, it will include <em>wp-includes\/theme-compat\/comments.php<\/em> from WordPress core.<\/li>\n<li><a href=\"https:\/\/developer.wordpress.org\/reference\/functions\/get_template_part\/\" target=\"_blank\"><code>get_template_part()<\/code><\/a> fetches custom includes such as the loop\u00a0for example. This helps you make your themes more efficient by only coding once. So if you have one <em>loop.php<\/em> file and call it in all your template files, then you only have to edit the code once if you want to change your loop.<\/li>\n<\/ul>\n<p>To use <code>get_template_part()<\/code> to call the <em>loop.php<\/em> file, you&#8217;d use this:<\/p>\n<p><span style=\"font-weight: 400;\"><div class=\"gist\" data-gist=\"a974e70c674d673f53114df889b158a8\" data-gist-file=\"get template part loop\"><a class=\"loading\" href=\"https:\/\/gist.github.com\/a974e70c674d673f53114df889b158a8.js?file=get+template+part+loop\">Loading gist a974e70c674d673f53114df889b158a8<\/a><div class=\"gist-consent-notice\" style=\"display:none\"><p>Please <a href=\"javascript:Cookiebot.renew()\">update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div><\/span><\/p>\n<h2 id=\"template-files-and-child-themes\">Template Files and Child Themes<\/h2>\n<p>But what if you&#8217;re using a child theme to modify a parent theme? You may be wondering how the template hierarchy works in that case.<\/p>\n<p>The good news is that it&#8217;s pretty\u00a0simple: WordPress will work through the template files for <strong>both<\/strong> themes and use the one that&#8217;s highest in the hierarchy. If both themes have the same file duplicated, then it will use the one from the child theme. This is how you use a child theme to override a template file in a parent theme.<\/p>\n<p>So for example, my parent theme has these files:<\/p>\n<ul>\n<li><em>index.php<\/em><\/li>\n<li><em>front-page.php<\/em><\/li>\n<li><em>page.php<\/em><\/li>\n<li><em>single.php<\/em><\/li>\n<li><em>archive.php<\/em><\/li>\n<li><em>category.php<\/em><\/li>\n<li><em>404.php<\/em><\/li>\n<li><em>search.php<\/em><\/li>\n<\/ul>\n<p>And my child theme has these files:<\/p>\n<ul>\n<li><em>front-page.php<\/em><\/li>\n<li><em>mypagetemplate.php<\/em><\/li>\n<li><em>single.php<\/em><\/li>\n<li><em>category.php<\/em><\/li>\n<li><em>taxonomy.php<\/em><\/li>\n<li><em>taxonomy-productcat-featured.php<\/em><\/li>\n<\/ul>\n<p>Which file do you think WordPress will use now for each of these pages?<\/p>\n<ul>\n<li>The home page (a static page)<\/li>\n<li>A static page<\/li>\n<li>A single post<\/li>\n<li>A product<\/li>\n<li>A product with\u00a0the\u00a0<em>featured<\/em>\u00a0term in the\u00a0<em>productcat<\/em>\u00a0taxonomy<\/li>\n<li>An error page<\/li>\n<li>A search page<\/li>\n<li>A category archive<\/li>\n<li>A tag archive.<\/li>\n<\/ul>\n<p>The answers are below.<\/p>\n<ul>\n<li>The home page:\u00a0<em>front-page.php<\/em> from the child theme<\/li>\n<li>A static page: <em>page.php<\/em> from the parent theme (or\u00a0<em>mypagetemplate.php<\/em>\u00a0from the child theme if I select that in the page admin screen)<\/li>\n<li>A single post:\u00a0<em>single.php<\/em> from the child theme<\/li>\n<li>A product:\u00a0<em>single.php<\/em> from the child theme<\/li>\n<li>A product\u00a0with\u00a0the\u00a0<em>featured<\/em>\u00a0term in the\u00a0<em>productcat<\/em>\u00a0taxonomy:\u00a0<em>taxonomy-productcat-featured.php<\/em> from the child theme<\/li>\n<li>An error page:\u00a0<em>404.php<\/em> from the parent theme<\/li>\n<li>A search page:\u00a0<em>search.php<\/em> from the parent theme<\/li>\n<li>A category archive:\u00a0<em>category.php<\/em> from the child theme<\/li>\n<li>A tag archive:\u00a0<em>archive.php<\/em>\u00a0from the parent\u00a0theme<\/li>\n<\/ul>\n<p>Note that if a template file from the parent theme is higher in the hierarchy than all the files in the child theme, then the file from the parent theme will be used. It&#8217;s only when the files are duplicated that the child theme&#8217;s file trumps the parent theme&#8217;s file, or if\u00a0the child theme&#8217;s file is higher in the hierarchy.<\/p>\n<h2>Understanding the Template Hierarchy Will Make You a Better <del>Person<\/del> Theme Developer<\/h2>\n<p>Phew! We&#8217;ve covered a lot in this post and I&#8217;ve asked you to do some thinking. Hopefully you now understand how the template hierarchy works and you can use it to identify which template file WordPress will use to display which page in your site.<\/p>\n<p>The template hierarchy is a great feature of WordPress: it keeps things clear and logical, and if you make reference to it when building your themes, you shouldn&#8217;t go wrong.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>If you&#8217;re building your own themes for WordPress, or using a child theme to customize a third party theme, at some point you&#8217;ll come across the template hierarchy. It&#8217;s a brilliant system that dictates how WordPress chooses which template file to use for different types of content. It takes into account content types (e.g. posts, [&hellip;]<\/p>\n","protected":false},"author":347011,"featured_media":162542,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"blog_reading_time":"","wds_primary_category":0,"wds_primary_tutorials_categories":0,"footnotes":""},"categories":[557,263],"tags":[],"tutorials_categories":[],"class_list":["post-162527","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-development","category-tutorials"],"_links":{"self":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts\/162527","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/users\/347011"}],"replies":[{"embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/comments?post=162527"}],"version-history":[{"count":18,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts\/162527\/revisions"}],"predecessor-version":[{"id":209650,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts\/162527\/revisions\/209650"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/media\/162542"}],"wp:attachment":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/media?parent=162527"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/categories?post=162527"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/tags?post=162527"},{"taxonomy":"tutorials_categories","embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/tutorials_categories?post=162527"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}