If you develop WordPress themes or use child themes to customize an existing one, you’ll eventually need to understand how the template hierarchy works.
The hierarchy determines which template file WordPress loads for each type of content – posts, pages, custom post types, taxonomies, and everything in between. It also lets you create unique templates for specific pages.
It can be confusing, though. Which file renders the archive page of a taxonomy tied to a custom post type? What about individual posts?
This guide covers the full hierarchy with examples for every content type.
Here’s a visual overview of the full hierarchy. Click a content type to highlight its cascade path:
Page Template Hierarchy – Types of Templates
Pages in WordPress are built from multiple template files. These are loaded using the get_template_part function, and each file handles a different section of the page.
Which template WordPress actually uses depends on the hierarchy. A more specific template always overrides a generic one. An example will make this clearer.
Let’s say a user visits the page “http://domain.com/author/roee“. WordPress will first look for a page template (file) named author-roee.php. If this file does not exist, WordPress will search for a file named author.php. If that doesn’t exist either and we continue to move up the hierarchy, WordPress will search for archive.php, and then index.php to render and display the page.
Every time someone visits a page, WordPress walks down the hierarchy until it finds a matching file. The filename itself tells WordPress whether to use it.
Essential Template Files
Every WordPress theme needs certain files to function. The two mandatory ones are index.php and style.css.
index.php sits at the top of the hierarchy and serves as the final fallback when no more specific template exists. style.css holds basic theme metadata (name, description, author) and is not a page template itself.
Apart from JavaScript and CSS assets, virtually every file in the theme directory is a template file. These fall into two groups: files outside the WordPress loop and files that contain it.
WordPress’s loop exists to fetch content from the database (preserved through the admin interface) and render them into actual pages on your site.
Files outside the loop handle the parts of the page that surround the main content. The header (header.php) contains HTML and meta tags that appear before the content. The footer (footer.php) holds everything after it.
sidebar.php is another common file outside the loop. It typically renders widgets and other secondary content alongside the main area.
comments.php controls how comments appear beneath posts. It can get complex, but at its core it’s just HTML and PHP describing the comment display.
These files matter, but the real structure of a WordPress site is determined by the template files inside the loop – the ones that render the actual content. Which file WordPress picks depends on the hierarchy and the filenames in your theme.
Front Page
The home page is usually the most important page in your theme. WordPress looks for index.php to render it, but index.php has a broader role: it’s the ultimate fallback for any page when no more specific template exists.
Two files specifically affect the home page: front-page.php and home.php. front-page.php has the highest priority. If it doesn’t exist, WordPress uses home.php or page.php depending on your Settings > Reading configuration (latest posts vs. static page).
The key difference: front-page.php is used only for the home page, while index.php serves as the default for everything else. The homepage hierarchy:
/*** Homepage Hierarchy ***/
front-page.php
home.php
page.php
index.php
Archive Pages
Archive pages display lists of posts from a specific group – author pages, category pages, date-based pages, and so on.
The default template for all archives is archive.php. It’s not required, and without it WordPress uses index.php. But having at least archive.php in your theme is a good practice. More specific archive templates can override it.
The basic archive hierarchy:
/*** Archive Hierarchy ***/
archive.php
index.php
Author Page
Author pages are a sub-type of archive pages. They show all posts by a specific author, like yoursite.com/author/username.
By default WordPress uses archive.php for these. Creating an author.php file overrides that default for all author pages.
You can be even more specific and add a file that renders content differently for a specific author. Create a file named author-[id].php or author-[nicename].php. In the example above, we could create author-roee.php to override both archive.php and author.php.
The author page hierarchy is a great example of how the cascade works in WordPress:
/*** Author Hierarchy ***/
author-[nicename].php
author-[id].php
author.php
archive.php
index.php
Category Page
Category pages work in the same way as author pages. For example, if you visit “http://yoursite.com/category/my-category“, by default WordPress will use archive.php. However, if you create a file named category.php, it will override the default, and WordPress will use this file to render the page.
Similar to author pages, you can specify the category using category-[slug].php or category-[id].php. In both cases, these files will take precedence over category.php.
The hierarchy for category pages is the same as for author pages:
/*** Category Hierarchy ***/
category-[slug].php
category-[id].php
category.php
archive.php
index.php
Additional Archive Pages
I hope the examples above help you understand how the hierarchy of archive pages works. But this hierarchy is not relevant only for author and category pages; it works for any taxonomy in WordPress.
For example, if you want a template only for tag pages, create tag.php or tag-[id].php for a specific tag. For date-based archives, create date.php.
For custom taxonomies, WordPress also supports the generic taxonomy.php fallback:
/*** Custom Taxonomy Hierarchy ***/
taxonomy-[taxonomy]-[term].php
taxonomy-[taxonomy].php
taxonomy.php
archive.php
index.php
There is one exception when it comes to archives of Custom Post Types. The default is still archive.php, but you can create a specific template using the format archive-[post_type_name].php.
For the complete list of template filenames, see the WordPress Developer Handbook.
Single Pages
With archive pages covered, let’s look at single pages. These are individual content pages: static pages, single posts, attachment pages, and custom post type entries.
Single Posts
Single posts are any individual content page under the Posts type or a custom post type. The general template is single.php. If that’s the only file in your theme, all individual posts – including attachments and custom post types – will use it.
Note that this file is not mandatory – if it doesn’t exist, WordPress will use the
index.phpfile to render the content.
If you want to define a template for a specific custom post type, you can create a file named single-[post_type_name].php. For example, if the custom post type is called “Portfolio,” then the file name should be single-portfolio.php.
You can also be more specific with attachment pages using attachment.php. For attachments you can go even deeper and set a template based on the MIME type, for example image.php or video.php.
Worth mentioning is singular.php – a shared fallback for both posts and pages. If single.php doesn’t exist, WordPress looks for singular.php before falling back to index.php.
/*** Single Post Hierarchy ***/
image.php (or video.php, text.php, etc.)
attachment.php
single-attachment.php
single-[post_type_name].php
single.php
singular.php
index.php
Static Pages
Pages (the “Pages” content type) work a bit differently. The default template is page.php, but it’s not required – without it WordPress falls back to singular.php and then index.php.
Unlike posts, you can target a specific page using page-[slug].php or page-[id].php. These templates apply only to that one page. Everything else uses page.php.
For pages, there’s also the option to choose the page template through the “Page Attributes > Template” section in the editor. If you select a Custom Template there, it will override any other template for that page – making it the top priority in the hierarchy.
Note that singular.php also applies here as a fallback if page.php doesn’t exist.
/*** Page Hierarchy ***/
custom template
page-[slug].php
page-[id].php
page.php
singular.php
index.php
Additional Page Templates
Beyond the templates we’ve covered, there are a few more worth knowing.
404 Template
The 404.php file is displayed when WordPress can’t find the requested page – a broken URL or deleted content. If this file doesn’t exist, WordPress falls back to index.php.
Search Template
The search.php file handles search result pages on your site. Without it, WordPress uses index.php to render search results.
Embed Template
Since WordPress 4.5, when your content is embedded on another site, WordPress looks for dedicated embed template files. The hierarchy is embed-[post-type]-[post-format].php, then embed-[post-type].php, then embed.php.
Privacy Policy Template
Since WordPress 5.2, you can create a dedicated template for the privacy policy page using privacy-policy.php. If it doesn’t exist, WordPress falls back to the regular page hierarchy (page.php, then index.php).
Block Themes and the Template Hierarchy
Block themes are the modern approach to WordPress theme development. Instead of .php files, block themes use .html files containing block markup.
These template files live in the /templates folder of the theme. The hierarchy itself is identical – same filenames, same priority order – only the file extension changes from .php to .html.
When users edit templates through the Site Editor, WordPress saves the changes as a wp_template custom post type in the database. The original theme template files remain untouched.
FAQs
Common questions about the WordPress template hierarchy:
index.php is the ultimate fallback template in the hierarchy. When WordPress cannot find any more specific template for a given content type, it uses index.php to render the page. In classic themes it is one of only two required files (alongside style.css).singular.php is a shared fallback template for both posts and pages. If single.php or page.php don't exist in your theme, WordPress will look for singular.php before falling back to index.php. It's useful when you want a single template for all individual content types..html files instead of .php. The template files are stored in the /templates folder of the theme. When a user edits a template through the Site Editor, WordPress saves the customized version in the database as a wp_template custom post type.page-about.php (by slug) or page-42.php (by ID). For posts you can create single-post-{slug}.php. You can also assign a Custom Template through the Page Attributes panel in the editor, which takes the highest priority in the hierarchy.front-page.php always takes priority for the site's front page, regardless of Reading settings. home.php is used for the front page only when Reading is set to "latest posts", or for the blog posts page when a static front page is configured.single.php in the child theme, that file overrides the parent theme's single.php. This is the recommended way to customize templates without editing the original theme files.Conclusion
The WordPress template hierarchy is essentially a naming convention. Follow the right filenames and WordPress picks the right template automatically. This system comes into play every time you develop or customize a WordPress theme.
In well-built themes you’ll find that each template is further broken into reusable parts using get_template_part(). If you need to pass data between those parts, check out the guide on passing variables to get_template_part. And if you want to create a custom page template, there’s a dedicated guide for that as well.
I’m confident that once you understand this hierarchy, building and modifying WordPress themes becomes much simpler.
