What is the WordPress Template Hierarchy? Priorities by Page Type

Last updated:

When WordPress generates a page, it determines which template file to call based on the template hierarchy. I will explain what a template hierarchy is with an example and introduce the template hierarchy for each type of page.

What is Template Hierarchy?

A template hierarchy is a system (rule) that WordPress uses to decide which template files to use when generating a page.

Each page type has a priority of which template file to call.

Look for the corresponding template file in the theme directory by file name.

How the template hierarchy works

The template file to be invoked is determined by the following process.

  1. Determine the type of page from the requested URL
  2. Find the template file at the top of the template hierarchy for each page type.
  3. Use the first matching template file
  4. If it doesn’t match, look for the next file in the hierarchy
  5. If none of them match, use index.php

Example of a template hierarchy

Let’s look at the flow of how the template file is selected when the category page is actually displayed.

  1. Category pages are requested
  2. If the category slug is test, use the template file category-test.php if you have one.
  3. If the category ID is 7, use the template file category-7.php if available.
  4. If you have a template file called category.php, use it
  5. Use a template file called archive.php if you have one
  6. Using index.php

Why do we need a template hierarchy?

If you have a WordPress template hierarchy, you don’t need to prepare a page for each URL.

If you have the same page structure, you can shorten your development time by calling the same template file.

When you create a theme, understanding the template hierarchy will help you to edit the appropriate template.

Template Hierarchy by Page Type

The following is the priority order of template files for each type of page to be displayed. They are arranged in order of priority.

Home Page

By default, WordPress is set up to display the latest posts on your homepage. This page is also called the Blog Post Index.

If “Your latest posts” is selected in the “Your homepage displays” section, it will have the following priority.

  1. front-page.php
  2. home.php
  3. index.php
Your latest posts

Front Page

If “Reading Settings” is selected in the “A static page” section, the priority is different depending on whether or not you have designated a Posts page for the Homepage.

Homepage

If “Homepage” is selected, the following priorities are in order.

  1. front-page.php
  2. Custom Template File
  3. page.php
  4. singular.php
  5. index.php
A static page

If you select a template for a given fixed page other than the “Default template“, the custom template file you select will be preferred.

Template

Posts page only

If the homepage is not selected and only the “Posts page” is selected, the following priorities will be given.

  1. front-page.php
  2. home.php
  3. singular.php
  4. index.php
Posts page

Privacy Page

The order of priority depends on whether or not you have selected “Privacy Policy” as your privacy policy page in the “Privacy Settings” section.

Privacy Policy Page

Privacy Policy

If “Privacy Policy” is selected, the following priorities will apply.

{slug} is the slug of the page and {id} is the ID of the page.

  1. privacy-policy.php
  2. Custom Template File
  3. page-{slug}.php
  4. page-{id}.php
  5. page.php
  6. singular.php
  7. index.php

If privacy-policy.php does not exist, if you select a fixed page template other than “default template” in the specified fixed page template, the custom template file you selected will take precedence.

Custom Template File

Except for Privacy Policy

If anything, other than “Privacy Policy” is selected, the following priorities will apply.

{slug} is the slug of the page and {id} is the ID of the page.

  1. Custom Template File
  2. page-{slug}.php
  3. page-{id}.php
  4. page.php
  5. singular.php
  6. index.php

Single Post Page

The single post pages will have the following priority.

{post-type} is the post type and {slug} is the slug of the post page.

  1. single-{post-type}-{slug}.php
  2. single-{post-type}.php
  3. single.php
  4. singular.php
  5. index.php

Single Page

Single pages are the following priorities.

{slug} is the slug of the page and {id} is the ID of the page.

  1. Custom Template File
  2. page-{slug}.php
  3. page-{id}.php
  4. page.php
  5. singular.php
  6. index.php

Category Page

Category pages are in the following order of priority.

{slug} is the slug of the category and {id} is the ID of the category.

  1. category-{slug}.php
  2. category-{id}.php
  3. category.php
  4. archive.php
  5. index.php

Tag Page

Tag pages are in the following order of priority.

{slug} is the slug of the tag and {id} is the tag ID.

  1. tag-{slug}.php
  2. tag-{id}.php
  3. tag.php
  4. archive.php
  5. index.php

Author Page

The author page is in the following order of priority.

{name} is the author’s user name and {id} is the author’s ID.

  1. author-{name}.php
  2. author-{id}.php
  3. author.php
  4. archive.php
  5. index.php

Date Page

The date pages are in the following order of priority.

  1. date.php
  2. archive.php
  3. index.php

Search Result page

The search results page will be in the following priority order.

  1. search.php
  2. index.php

404 （Not Found）Page

404 (Not Found) pages have the following priority.

  1. 404.php
  2. index.php

Attachment Page

Attachment pages are in the following order of priority.

{MIME-type} is for image/video/pdf, etc. {slug} is the slug of the attachment.

  1. {MIME-type}.php
  2. attachment.php
  3. single-attachment-{slug}.php
  4. single-attachment.php
  5. single.php
  6. singular.php
  7. index.php

Priority when {MIME-type} is text-plain.

  1. text-plain.php
  2. plain.php
  3. text.php

Embeds Page

Embed pages are prioritized in the following order

{post-type} is the post type and {post-format} is the post format.

  1. embed-{post-type}-{post-format}.php
  2. embed-{post-type}.php 
  3. embed.php
  4. wp-includes/theme-compat/embed.php

Custom Post Type Page

Custom post type pages will have the following priority.

{post-type} is filled with the post type.

  1. archive-{post-type}.php
  2. archive.php
  3. index.php

Custom Taxonomy Pages

Custom taxonomy pages have the following priority.

{taxonomy} is a taxonomy and {term} is a term.

  1. taxonomy-{taxonomy}-{term}.php
  2. taxonomy-{taxonomy}.php
  3. taxonomy.php
  4. archive.php
  5. index.php
go to top