Skip to content

The WordPress Template Hierarchy

A visual guide, updated for WordPress 4.8.

How to use this table

Start on the appropriate Entry Point and move along the row from left (more specific) to right (more general) to understand the template hierarchy for the page that needs to be displayed.

For the more general templates, look to the left of the cell to understand which types of pages fall back to that template if more specific ones are not implemented in your theme.

A guide to conventions
Entry Point WordPress uses a series of checks (Conditional Tags) to decide what kind of page needs to be displayed
Variable template file name Includes some aspect of the page to display
Constant template file name Does not depend on any aspect of the page to display
Conditional If a certain condition is met, the template is applied; see footnotes for explanations.
Base template The last template in a chain, it must exist in your theme.
The WordPress 4.8 Template Hierarchy
Archive Pages Date Archive date.php archive.php index.php6
Author Archive author-$nicename.php author-$id.php author.php
Tag Archive tag-$slug.php1 tag-$term_id.php tag.php
Category Archive category-$slug.php1 category-$term_id.php category.php
Custom Taxonomy Archive2 taxonomy-$taxonomy-$term_slug.php1 taxonomy-$taxonomy.php taxonomy.php
Custom Post Type Archive archive-$post_type.php
Singular Pages Attachment Post $type-$subtype.php3 $subtype.php3 $type.php3 attachment.php3 single-$post_type-$slug.php1 single-$post_type.php single.php singular.php
Single Post Custom Page Template4
Single Page page-$slug.php1 page-$id.php page.php
Other Pages Search Results search.php
Missing Page 404.php
Home Page home.php
Front Page Front Page front-page.php Home Page or Single Page5
Embedded Content oEmbed Post embed-$post_type-$post_format.php embed-$post_type.php embed.php theme-compat/embed.php

I built this chart by looking through the WordPress source code:


1 WordPress stores the $slug in url-encoded format, with special characters encoded as %XY. For example, the thinking face emoji character (🤔) is encoded as %F0%9F%A4%94. As of version 4.7, WordPress will first try to match the decoded variant (e.g. 🤔.php), then the encoded one (e.g. %F0%9F%A4%94.php).

2 The post's format is considered a custom taxonomy, whose slug is post_format, and whose terms are post-format-link, post-format-quote, etc.

3 Attachment-related templates don't follow a logic hierarchy from more specific to less specific. You can handle these in the single-attachment.php template instead.

4 If the page has a Custom Page Template assigned to it, that template will be used. As of version 4.7, Custom Page Templates can be applied to all types of posts, not just Pages.

5 The user can configure what to show on the Front Page: either the content of the Home Page, or that of a specific page in the website.

6 The index.php file is technically not necessary for the hierarchy (as long as you have templates to cover all cases), but you still need to have one for the theme to be valid.