The WordPress template hierarchy determines which PHP file is used to render each page on your site. When a visitor requests a URL, WordPress follows a specific order of template file checks, starting with the most specific and falling back to more general templates. Understanding this hierarchy is essential for theme development.<\/p>
This guide breaks down the WordPress template hierarchy, showing exactly which templates are checked for each type of page.<\/p>
The homepage template selection depends on your reading settings. If your homepage displays your latest posts, WordPress checks for front-page.php, then home.php, then index.php. If your homepage uses a static page, WordPress uses the selected page’s template or front-page.php.<\/p>
Most themes create a front-page.php for the homepage and a home.php for the blog posts index page. If neither exists, index.php handles everything.<\/p>
Single post templates follow a specific hierarchy. WordPress first checks for single-post-{slug}.php (e.g., single-post-hello-world.php). If that doesn’t exist, it checks single-post-{id}.php. Then single.php, then singular.php, and finally index.php.<\/p>
For custom post types, WordPress checks single-{posttype}-{slug}.php, then single-{posttype}.php, then single.php, singular.php, and index.php. This allows you to create unique templates for each post type.<\/p>
Pages follow a similar hierarchy to posts. WordPress checks for the page’s custom template (set in the Page Attributes meta box), then page-{slug}.php, page-{id}.php, page.php, singular.php, and index.php.<\/p>
Custom page templates are created by adding a Template Name header comment to a PHP file in your theme directory. The template appears as an option in the Page Attributes meta box on page editing screens.<\/p>
Archive pages display lists of posts. WordPress checks for archive.php for all archives, then more specific templates: category-{slug}.php and category-{id}.php for category archives, tag-{slug}.php and tag-{id}.php for tag archives, author-{nicename}.php and author-{id}.php for author archives, date.php for date-based archives, and finally index.php if none of the above exist.<\/p>
For custom taxonomy archives, WordPress checks taxonomy-{taxonomy}-{term}.php, then taxonomy-{taxonomy}.php, then archive.php, and index.php.<\/p>
Search results use search.php if it exists, or index.php if it doesn’t. You can customize the search results template to show search suggestions, highlight matching terms, or provide filters for post types.<\/p>
The 404 page uses 404.php if it exists, or index.php as a fallback. Every theme should include a 404.php template that provides useful navigation options \u2014 search form, recent posts, category list \u2014 to help lost visitors find what they’re looking for.<\/p>
Block themes use a different template system. Templates are HTML files in the \/templates directory with block markup instead of PHP. The hierarchy works similarly: WordPress checks for the most specific template first, falling back to more general ones. Block themes have replaced the PHP template hierarchy with a block-based equivalent that’s still in development.<\/p>
The WordPress template hierarchy is logical and extensible. Specific templates override general ones. Start with index.php as your catch-all, then add more specific templates as needed. The hierarchy lets you create precise designs for different content types while maintaining a consistent fallback for anything you haven’t explicitly templated.<\/p>","protected":false},"excerpt":{"rendered":"
A comprehensive guide to the WordPress template hierarchy, with flowcharts showing how WordPress chooses which template files to use for each type of page.<\/p>","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"ai_primary_source":"","visibility_scope":"","ai_summary":"","ai_intent":"","ai_related_resources":"","ai_priority":0,"ai_entity_type":"","ai_is_based_on":"","ai_citations":"","ai_mentions":"","ai_speakable_selector":"","ai_chunk_hints":"","footnotes":""},"categories":[7,6],"tags":[44,27,35],"ai_visibility":[],"class_list":["post-599","post","type-post","status-publish","format-standard","hentry","category-web-development","category-wordpress","tag-api-first","tag-developer-to-founder","tag-saas"],"blocksy_meta":[],"_links":{"self":[{"href":"https:\/\/aarkly.com\/it\/wp-json\/wp\/v2\/posts\/599","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/aarkly.com\/it\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/aarkly.com\/it\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/aarkly.com\/it\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/aarkly.com\/it\/wp-json\/wp\/v2\/comments?post=599"}],"version-history":[{"count":1,"href":"https:\/\/aarkly.com\/it\/wp-json\/wp\/v2\/posts\/599\/revisions"}],"predecessor-version":[{"id":814,"href":"https:\/\/aarkly.com\/it\/wp-json\/wp\/v2\/posts\/599\/revisions\/814"}],"wp:attachment":[{"href":"https:\/\/aarkly.com\/it\/wp-json\/wp\/v2\/media?parent=599"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/aarkly.com\/it\/wp-json\/wp\/v2\/categories?post=599"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/aarkly.com\/it\/wp-json\/wp\/v2\/tags?post=599"},{"taxonomy":"ai_visibility","embeddable":true,"href":"https:\/\/aarkly.com\/it\/wp-json\/wp\/v2\/ai_visibility?post=599"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}