WordPress Template Hierarchy and Customization Guide

Homepage Template Hierarchy

WordPress homepage display is configured in Settings → Reading. You can choose to show your latest posts or a static page.

The template hierarchy for the homepage is as follows (highest priority first):

• front-page.php – Used first, regardless of homepage setting (posts or static page).
• home.php – Used if the homepage is set to show latest posts and front-page.php is not found.
• page.php – Used if the homepage is set to a static page and front-page.php is not found.
• index.php – The default fallback if none of the above templates exist.

Single Post, Page & Custom Post Type Templates

For single content items (posts, pages, custom post types), WordPress follows a specific-to-generic template loading order.

Template Name Placeholders

Placeholders in curly braces {} are dynamically replaced:

• {post-type}: The post type slug (e.g., single-product.php).
• {slug}: The post's slug/permalink name (e.g., single-hello.php).
• {id}: The post's numeric ID (e.g., single-1.php).

Loading Priority

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

Taxonomy Archive Templates

Archive pages display lists of posts belonging to a taxonomy term.

Template Name Placeholders

• {taxonomy}: The taxonomy name (e.g., product_cat in taxonomy-product_cat.php).
• {term}: The term slug (e.g., cat1 in taxonomy-product_cat-cat1.php).

Loading Priority

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

Category Archive Templates

Categories are a built-in taxonomy. The template prefix is category.

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

Post Type Archive Templates

Post type archives list all posts of a given type. {post_type} is the post type slug (e.g., archive-product.php).

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

Tag Archive Templates

Tags are a built-in taxonomy. The template prefix is tag.

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

Author Archive Templates

Author archives list all posts by a specific author. {nicename} corresponds to the user_nicename field, {id} is the author's numeric ID.

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

Date Archive Templates

Date archives list posts published in a specific time period.

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

Note: WordPress does not have specific year/month/day templates (e.g., archive-2024.php). Use date.php or archive.php with conditional tags for finer control.

Search Results Template

Search results are a special type of archive.

• search.php
• index.php

404 Error Page Template

The 404 page is displayed when content is not found.

• 404.php
• index.php

Attachment Templates

Attachments are a special post type. Templates can be targeted by MIME type (e.g., video-mp4.php for a custom video player).

• {MIME-type}.php (e.g., video-mp4.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 control how a post appears when embedded on other sites.

• embed-{post-type}-{post_format}.php
• embed-{post-type}.php
• embed.php
• wp-includes/theme-compat/embed.php (core fallback)