WordPress Template Hierarchy

This tutorial explains that how Wordpress template  loader uses the queried information for a page to build a template hierarchy, tghen it searches the valid templates for the hierarchy.

WordPress determines the suitable template or combination of templates to display a page by analyzing the query string. The query string is information or data embedded from the URL that gives direction to the system for specific content or sections of your site.

Visual Representation of Template Hierarchy :

WordPress Template Hierarchy
For simplicity we will describe template hierarchy in below parts:
  1. Home or Front Page Template Hierarchy
  2. Blog Category Single Page (Archive for a Category)
  3. Blog Post Detail Page (Single Post)
  4. Tag Detail Page (Archive for a Tag)
  5. Static Page Template Hierarchy
  6. Custom Post Type Archive Page
  7. Taxonomy Archive Pages (for Custom Post Types) Template Hierarchy
  8. Single Custom Post Type Page (Detail Page)
  9. Product Category Page Template Hierarchy
  10. Product Detail Page Template Hierarchy
  11. Search Result Page Template Hierarchy
  12. Privacy Policy Page display Template Hierarchy
  13. Author Page  (Archive for a Author) Template Hierarchy
  14. Date (Archive for a Date Based) Template Hierarchy


Home or Front Page Template Hierarchy

  1. front-page.php :- Used for both "latest posts" or "a static page" according to the settings of Settings → Reading.
  2. home.php :- If WordPress cannot find front-page.php and "latest posts" is set in the front page displays section, it will look for home.php. Additionally, WordPress will look for this file when the posts page is set in the front page displays section.
  3. page.php :- When "front page" is set in the front page displays section.
  4. index.php :- When "latest posts" is set in the front page displays section but home.php does not exist or when front page is set but page.php does not exist.


Blog Category Single Page (Archive for a Category)

The blog category page is an archive page that lists all posts within a specific category.

Template Hierarchy for Category Pages:

  1. category-{slug}.php: If a file named category-{slug}.php exists, WordPress will use it. Example: For a category with the slug news, WordPress uses category-news.php.
  2. category-{id}.php: If a file named category-{id}.php exists, WordPress will use it. Example: For a category with an ID of 5, WordPress uses category-5.php.
  3. category.php: If neither of the above files exists, WordPress falls back to category.php.
  4. archive.php: If category.php does not exist, WordPress uses archive.php as the fallback for all archive pages.
  5. index.php: If none of the above files exist, WordPress falls back to index.php


Blog Post Detail Page (Single Post)

The blog post detail page is for displaying a single blog post.

Template Hierarchy for Single Posts:

  1. single-{post_type}.php: If a file named single-{post_type}.php exists, WordPress will use it. Example: For posts of the default post type, WordPress uses single-post.php.
  2. single.php: If single-{post_type}.php does not exist, WordPress falls back to single.php.
  3. singular.php: If single.php does not exist, WordPress uses singular.php for any singular content type.
  4. index.php: If none of the above files exist, WordPress falls back to index.php.


Tag Detail Page (Archive for a Tag)

The tag detail page is for displaying a single blog post.

    Template Hierarchy for tag detail page:

    1. tag-{slug}.php :– If the tag’s slug is sometag, WordPress will look for tag-sometag.php.
    2. tag-{id}.php – If the tag’s ID is 6, WordPress will look for tag-6.php.
    3. tag.php :- If neither of the above files exists, WordPress falls back to tag.php.
    4. archive.php :- If tag.php does not exist, WordPress uses archive.php as the fallback for all archive pages.
    5. index.php :- If none of the above files exist, WordPress falls back to index.php


    Static Page Template Hierarchy

    For static pages (for example, "About Us," "Contact us" etc pages), WordPress follows this hierarchy:

    1. page-{slug}.php:- If a file named page-{slug}.php exists, WordPress uses it.
    2. Example:- For a page with the slug about, it looks for page-about.php.
    3. page-{id}.php:- If page-{slug}.php is unavailable, it looks for page-{id}.php. Example: For a page with ID 10, it looks for page-10.php.
    4. page.php:- If neither of the above files exists, WordPress uses page.php.
    5. singular.php:-  If page.php is unavailable, WordPress falls back to singular.php.
    6. index.php:- If none of the above files exist, WordPress defaults to index.php.


    Custom Post Type Archive Page

    For the archive page of a custom post type (if the  has_archive option is enabled in the custom post type definition), WordPress follows this hierarchy:

    1. archive-{post_type}.php:- Template for the custom post type archive. Example: For a custom post type books, WordPress looks for archive-books.php.
    2. archive.php:- Generic archive template.
    3. index.php:-  Final fallback template.


    Taxonomy Archive Pages (for Custom Post Types) Template Hierarchy

    If the custom post type has custom taxonomies (for example: genres for books), WordPress follows this hierarchy for taxonomy archive pages:

    1. taxonomy-{taxonomy}-{term}.php:- Template for a specific term in a taxonomy. Example: For the taxonomy genres and the term fiction, WordPress looks for taxonomy-genres-fiction.php.
    2. taxonomy-{taxonomy}.php:- General template for the taxonomy. Example: For the taxonomy genres, WordPress looks for taxonomy-genres.php.
    3. taxonomy.php:- Generic template for all taxonomies.
    4. archive.php:- Generic archive template.


    Single Custom Post Type Page (Detail Page)

    For a single post of a custom post type (e.g., books), WordPress checks the following templates in this order:

    1. single-{post_type}-{slug}.php:- Template for a specific post within the custom post type. Example: For a custom post type books and a post with the slug harry-potter, WordPress looks for single-books-harry-potter.php.
    2. single-{post_type}.php:- General template for the custom post type. Example: For a custom post type books, WordPress looks for single-books.php.
    3. single.php:- Final fallback template.


    Product Category Page Template Hierarchy

    For product category pages (archive pages for a product category), WooCommerce follows this hierarchy:

    1. taxonomy-product_cat-{slug}.php:- Looks for a file named after the category slug. Example: For the category "shoes," it looks for taxonomy-product_cat-shoes.php.
    2. taxonomy-product_cat.php:- If taxonomy-product_cat-{slug}.php doesn’t exist, it falls back to this file.
    3. archive-product.php:- If no category-specific template exists, WooCommerce uses the general product archive template.
    4. archive.php:- If archive-product.php doesn’t exist, it uses the WordPress archive template.
    5. index.php:-  If no other templates exist, it defaults to index.php


    Product Detail Page Template Hierarchy

    For single product detail pages, WooCommerce follows this hierarchy:

    1. single-product-{slug}.php:- Looks for a file specific to the product slug. Example: For a product slug red-shoe, it looks for single-product-red-shoe.php.
    2. single-product.php:- If no slug-specific template exists, it uses this file.
    3. singular.php:- If single-product.php doesn’t exist, WordPress falls back to singular.php.
    4. index.php:- If no other templates exist, WordPress defaults to index.php.


    Search Result Page Template Hierarchy

    1. search.php:- Looks for a specific  file search.php to show search result.
    2. index.php:-  If the above templates not exist, WordPress defaults to index.php


    Privacy Policy Page display Template Hierarchy

    1. privacy-policy.php – Looks for the Privacy Policy page set in the Change your Privacy Policy page section of Settings → Privacy.
    2. page-{slug}.php:– If the page slug is privacy, WordPress will look to use page-privacy.php.
    3. page-{id}.php:– If the page ID is 6, WordPress will look to use page-6.php.
    4. page.php:- If the above templates not exist, WordPress fallback to page.php
    5. singular.php:  If the above templates not exist, WordPress fallback to singular.php
    6. index.php:-  If the above templates not exist, WordPress fallback to default index.php


    Author Page  (Archive for a Author) Template Hierarchy

    1. author-{nicename}.php – If the author’s nice name is matt, WordPress will look for author-matt.php.
    2. author-{id}.php:– If the author’s ID were 6, WordPress will look for author-6.php.
    3. author.php:-  If the above templates not exist, WordPress fallback to author.php
    4. archive.php:-  If the above templates not exist, WordPress fallback to archive.php
    5. index.php:- If the above templates not exist, WordPress fallback to default index.php


    Date (Archive for a Date Based) Template Hierarchy

    1. date.php:- Wordpress Looks for a specific  file date.php to show search result.
    2. archive.php:-  If the above templates not exist, WordPress fallback to archive.php
    3. index.php:-  If the above templates not exist, WordPress fallback to default index.php

    Leave a comment

    Feature Posts