When developing a WordPress theme, one of the most important concepts to grasp is the template hierarchy. This hierarchy dictates the order in which WordPress selects template files to display different types of content. Understanding the structure of these files will help us customize our theme effectively, ensuring that our website renders exactly the way we want it to across various pages and post types.

What is Template Hierarchy?

Template hierarchy in WordPress refers to the system WordPress uses to determine which template file to use when rendering content on our site. WordPress checks for specific template files in a predetermined order to match the content being displayed. If the required template file is not found, WordPress falls back to more general templates, eventually using the index.php file as the final fallback.

The template hierarchy can be best understood with a series of rules for how WordPress selects templates based on the type of content we are viewing. Below, is an infographic on how WordPress handles different types of pages, including the home page, single posts, pages, categories, and more.

Home Page Display

By default, WordPress sets our site’s home page to display our latest blog posts, known as the “blog posts index”. We can also configure WordPress to display a static page instead. Here’s how WordPress selects the template for the home page:

1. front-page.php – If this template file exists, WordPress uses it for the front page, whether we’re displaying our latest posts or a static page.
2. home.php – If no front-page.php is found, WordPress will use home.php to render the blog posts index, regardless of whether it’s set as the front page or a separate static page.
3. page.php – If home.php is absent and the front page is a static page, WordPress will check for page.php to render the content.
4. index.php – If neither front-page.php, home.php, nor page.php exists, WordPress defaults to index.php.

---

Front Page Display

The front-page.php template is used for the site’s front page, which may either show our latest posts or a static page, depending on our Settings → Reading preferences. Here’s the order of precedence:

1. front-page.php – The most specific template for the front page, regardless of whether it displays posts or a static page.
2. home.php – If front-page.php is absent and our home page is set to show our latest posts, WordPress will use home.php.
3. page.php – If a static page is set as the front page, WordPress will fall back to page.php.
4. index.php – The ultimate fallback if no other templates are found.

---

Privacy Policy Page

The Privacy Policy page is handled by a unique template:

1. privacy-policy.php – WordPress looks for this file when rendering the Privacy Policy page as set in Settings → Privacy.
2. custom template – If assigned a custom template to the page, WordPress will use that.
3. page-{slug}.php – If Privacy Policy page’s slug is “privacy,” WordPress will search for page-privacy.php.
4. page-{id}.php – If the page ID is known, WordPress will look for a template based on the page ID, such as page-6.php.
5. page.php, singular.php, index.php – These templates serve as fallbacks if no specific template for the Privacy Policy is found.

---

Single Post Display

For single posts (whether a regular post or custom post type), WordPress follows this path:

1. single-{post-type}-{slug}.php – If a custom post type is used, WordPress will first check for a file named according to the post type and slug. For example, single-product-dmc-12.php for a product post with the slug dmc-12.
2. single-{post-type}.php – If no slug-specific file exists, WordPress will look for a general template like single-product.php for the post type.
3. single.php – If no post type-specific templates are found, WordPress defaults to single.php for rendering individual posts.
4. singular.php – A broader fallback for rendering singular posts, regardless of post type.
5. index.php – The ultimate fallback.

---

Single Page Display

When rendering static pages, WordPress uses the following hierarchy:

1. custom template – If a custom page template is assigned, WordPress will use it.
2. page-{slug}.php – If a page has a specific slug (e.g., recent-news), WordPress will look for page-recent-news.php.
3. page-{id}.php – If the page has a specific ID, WordPress will check for a template based on the ID (e.g., page-6.php).
4. page.php – The default template for regular static pages.
5. singular.php – Used if no specific page template is found.
6. index.php – The final fallback.

---

Category and Tag Archives

For category and tag archives, WordPress follows these paths:

1. category-{slug}.php / tag-{slug}.php – WordPress looks for category- or tag-specific templates based on their slug.
2. category-{id}.php / tag-{id}.php – If no slug-based template is found, WordPress will look for templates based on the category or tag ID.
3. category.php / tag.php – General templates for categories and tags.
4. archive.php – If no category/tag template is available, WordPress checks archive.php.
5. index.php – The final fallback.

---

Custom Taxonomies

Custom taxonomies use a slightly different template path:

1. taxonomy-{taxonomy}-{term}.php – For custom taxonomies, WordPress looks for a file based on the taxonomy and term (e.g., taxonomy-category-news.php).
2. taxonomy-{taxonomy}.php – If no term-specific template exists, WordPress falls back to the taxonomy template (e.g., taxonomy-category.php).
3. taxonomy.php – A general fallback for taxonomies.
4. archive.php – The fallback for archive pages, including those for taxonomies.
5. index.php – The final fallback.

---

Custom Post Types (CPT)

For custom post types, the hierarchy looks like this:

1. archive-{post_type}.php – WordPress will first search for an archive template specific to the custom post type (e.g., archive-product.php for a “product” post type).
2. archive.php – If no custom archive template is found, WordPress will fall back to the general archive.php.
3. index.php – The ultimate fallback.

---

Author Archives

When displaying an author archive, WordPress will look for:

1. author-{nicename}.php – A template specific to the author’s nicename (e.g., author-john.php).
2. author-{id}.php – A template based on the author’s ID (e.g., author-6.php).
3. author.php – The general author archive template.
4. archive.php – The general fallback for archive templates.
5. index.php – The final fallback.

---

404 Pages

If a page cannot be found (a 404 error), WordPress will search for the following:

1. 404.php – The specific template for 404 errors.
2. index.php – If no 404.php template is found, WordPress will use index.php as the fallback.

---

Attachment Pages

When rendering an attachment page (for example, when viewing an image or document), WordPress follows this path:

1. {MIME-type}.php – WordPress looks for a template file specific to the MIME type (e.g., image.php or video.php).
2. single-attachment-{slug}.php – If an attachment has a slug (e.g., holiday), WordPress will look for single-attachment-holiday.php.
3. attachment.php – A general template for attachments.
4. single.php – A fallback for single attachment pages.
5. singular.php – Another fallback.
6. index.php – The final fallback.

Conclusion

The WordPress template hierarchy is a powerful system that allows us to customize and control how different types of content are displayed on our site. By understanding the rules behind the hierarchy, we can create a more flexible and tailored theme for our WordPress site. While it may seem complex at first, once we become familiar with how WordPress searches for templates, we’ll be able to design custom templates that ensure the site looks great across all pages and content types.

For more detailed customization, refer to the official WordPress documentation and experiment with template files to see which ones are being used for specific content.