WordPress Template Hierarchy

The Template File Hierarchy is the system WordPress utilizes to display the appropriate template or templates for a page. The template file is determined by comparing information in the query string (displayed in the page's URI) to files in the theme's folder, in hierarchical order. It first matches the query string to a query type to determine what kind of page is being displayed, then scans through files in the template hierarchy order, and finally uses the first matching template file with the name specified by the query string.

Order

For a singular page, the order in which WordPress searches for a template file is as follows:

  1. The page type is determined to be either a single post page or a static page.
  2. If a single post page:
    • The post type is determined: either an attachment post, custom post, or blog post
    • For attachment postsWordPress searches for a file of type "$mimetype-$subtype.php." If no page is found, "$subtype.php" is searched for instead; if this is also not found, "$mimetype.php" is searched for; if still not found, it proceeds to search for "attachment.php," "single.php," "singular.php," and if no other page can be displayed, it defaults to "index.php."
    • For custom posts and blog posts, WordPress searches for "$custom.php" if selected. If not found, a custom post template is searched for as "single-$posttype-$slug." If a slug matching the query string is not found, it searches instead for "single-$posttype." As with other singular post pages, the final files searched for are "single.php," "singular.php", and "index.php" if no other conditions are met.
    • If no custom file is found for a blog post, it searches for a file called "single-post.php". If no file is found, it searches for the final three .php files in order: single, singular, and index.
  3. If a static page:
    • WordPress searches for a page template, either custom or default.
    • If using a custom template, "$custom.php" is searched for.
    • If using a default template, WordPress does not search for "$custom.php," and the final files searched for are the same for either template.
    • "page-$slug.php" is searched for next.
    • If not found, "page-$id.php" is searched for.
    • If no custom template file are found, WordPress defaults to "page.php"; then to "singular.php"; and finally to "index.php."

File Naming Conventions

WordPress searches for files based on information passed to it via the query string. If the slug for a singular page is "contact", its ID is "10," and no custom template file is found, WordPress will search for files matching the naming conventions it expects: "page-contact.php," followed by "page-10.php." No matter what custom slug, ID, post-type or other identifiers the file contains, any page will ultimately resolve to "single.php" or "page.php", then to "singular.php", and finally to "index.php" if no previous file is found. It is important to match these naming conventions when creating custom template files to ensure WordPress can match the query string data with filenames in the theme directory.

Flowchart displaying the WordPress Template Hierarchy System
Visual flowchart of the WordPress Template Hierarchy

Summary

The Template Hierarchy System is the method WordPress uses to search for custom template files, determined on information such as page type, post type, tags, slugs, IDs, and other data obtained from the query string. WordPress filters through each type of file, finding the first matching template or set of template files to use to display the page. All pages or posts will display "index.php" if no other more specific page is found. If the file name does not match the naming conventions WordPress expects, it will not be selected and the next file in the hierarchy will be searched for instead.