WordPress Template Hierarchy

A visual guide, includes updates 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 Template Hierarchy v4.8

Archive Pages

Date Archive

date.php

archive.php

index.php

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

Footnotes

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.

Spotted an error?

Please let me know on this project's GitHub repo!