WordPress Template Hierarchy Rules for the Front Page, Single Posts, Pages, Archives, and More

In WordPress, a theme controls how the site looks, and that theme is made up of template files. When a visitor opens a page, WordPress fetches the right data from the database and then chooses the most specific available template file to render that request.

If you want to develop WordPress themes or even make reliable theme customizations, you need to understand the template hierarchy. It is one of the first things worth learning because it explains why WordPress loads one file instead of another.

Front page templates

WordPress lets you choose, in Settings → Reading, whether the homepage should show your latest posts or a static page. The homepage template priority works like this:

• front-page.php — highest priority whether the homepage shows latest posts or a static page.
• home.php — used when the homepage is set to show the latest posts and front-page.php is not present.
• page.php — used when the homepage is set to a static page and front-page.php is not present.
• index.php — the final fallback when none of the files above exist.

Templates for posts, pages, and custom post type singular views

Posts, pages, and custom post type single views are all singular content views. Their template lookup order generally moves from the most specific file to the most generic file.

In the file names below, the placeholders inside braces represent post data:

• {post-type} is the post type name, such as single-product.php.
• {slug} is the post slug, such as single-hello.php.
• {id} is the post ID, such as single-1.php.

Single posts and custom post type single views

• single-{post-type}-{slug}.php
• single-{post-type}.php
• single-{slug}.php
• single.php
• singular.php
• index.php

Pages

• page-{slug}.php
• page-{id}.php
• page.php
• single.php
• singular.php
• index.php

Taxonomy archive templates

Archive views list multiple posts. Just like singular templates, archive templates are selected from the most specific match down to a generic fallback.

In the names below, the placeholders stand for archive data:

• {taxonomy} is the taxonomy name, such as the product_cat part of taxonomy-product_cat.php.
• {term} is the term slug, such as the cat1 part of taxonomy-product_cat-cat1.php.

Custom taxonomy archive priority

• taxonomy-{taxonomy}-{term}.php
• taxonomy-{taxonomy}.php
• taxonomy.php
• archive.php
• index.php

Category archives

Categories are a built-in taxonomy in WordPress, so their hierarchy is similar to custom taxonomy archives, but without the taxonomy- prefix.

• category-{slug}.php
• category-{id}.php
• category.php
• archive.php
• index.php

Tag archives

Tags are also a built-in taxonomy, and they follow a similar hierarchy to categories.

• tag-{slug}.php
• tag-{id}.php
• tag.php
• archive.php
• index.php

Post type archives

A post type archive displays all posts that belong to a post type. This hierarchy is simpler. Here, {post_type} is the post type slug, as in archive-product.php.

• archive-{post_type}.php
• archive.php
• index.php

Author archives

An author archive shows all posts published by a specific author. {nicename} refers to the user’s user_nicename field, and {id} is the author ID.

• author-{nicename}.php
• author-{id}.php
• author.php
• archive.php
• index.php

Date archives

Date archives group posts published in a specific time period. Their hierarchy is:

• date.php
• archive.php
• index.php

Search results

Search results are also an archive view. In most themes the dedicated file is search.php; if that does not exist, WordPress falls back to index.php.

• search.php
• index.php

404 templates

When no matching content can be found, WordPress loads the 404 template. That makes 404.php the right place for a custom not-found page.

• 404.php
• index.php

Attachment templates

Attachments are also a post type, but they can be targeted in more specific ways. For example, a video attachment page could use a custom template to output a specialized player.

• {mime-type}.php
• text-plain.php
• plain.php
• text.php
• attachment.php
• single-attachment-{slug}.php
• single-attachment.php
• single.php
• singular.php
• index.php

Embed templates

Embed templates are used when a post is embedded into another page or website. You can create the following files to customize the appearance of embedded content:

• embed-{post-type}-{post_format}.php
• embed-{post-type}.php
• embed.php
• the fallback wp-includes/theme-compat/embed.php template

WordPress template hierarchy diagram

If the hierarchy above still feels abstract, keep the official template hierarchy diagram nearby. It is a useful visual reference when you need to decide which file WordPress will load.

Understanding template priority is one of the most important first steps in WordPress development. Once you are comfortable with it, you can move on to custom loops, custom post displays, and more advanced theme work.