Template Hierarchy
The WordPress Template Hierarchy is the system that determines which PHP template file is used to render a given page request. It follows a specific order of precedence, starting with the most specific template file (like single-post.php) and falling back to less specific files (like index.php) when more specific ones don't exist.
§ 1 Definition
The Template Hierarchy is WordPress's built-in system for mapping URL requests to theme template files. When a visitor requests a URL, WordPress analyzes the request type (home page, single post, archive page, search results, etc.) and selects the most specific template file available in the active theme. The hierarchy is a cascading fallback system. WordPress starts with the most specific template file that matches the request and moves down the chain until it finds a file that exists. If no matching template exists at any level, it falls back to `index.php`, which is the only required file in any WordPress theme. Understanding the template hierarchy is essential for WordPress theme development. It lets you create custom layouts for different content types without writing complex conditional logic. A `single-product.php` file automatically renders single product pages. A `category-videos.php` file automatically renders the 'Videos' category archive. The hierarchy handles the routing.
§ 2 The Hierarchy in Detail
Here's how WordPress resolves template files for common request types, in order of priority (most specific first): Home/Front Page: 1. `front-page.php` 2. `home.php` 3. `index.php` Single Post: 1. `single-{post-type}-{slug}.php` (e.g., `single-post-hello-world.php`) 2. `single-{post-type}.php` (e.g., `single-post.php` or `single-product.php`) 3. `single.php` 4. `singular.php` 5. `index.php` Page: 1. `pagename-{slug}.php` (e.g., `pagename-about-us.php`) 2. `page-{id}.php` (e.g., `page-42.php`) 3. `page.php` 4. `singular.php` 5. `index.php` Category Archive: 1. `category-{slug}.php` (e.g., `category-news.php`) 2. `category-{id}.php` (e.g., `category-5.php`) 3. `category.php` 4. `archive.php` 5. `index.php` Tag Archive: 1. `tag-{slug}.php` (e.g., `tag-wordpress.php`) 2. `tag-{id}.php` 3. `tag.php` 4. `archive.php` 5. `index.php` Custom Taxonomy Archive: 1. `taxonomy-{taxonomy}-{term}.php` (e.g., `taxonomy-genre-science-fiction.php`) 2. `taxonomy-{taxonomy}.php` (e.g., `taxonomy-genre.php`) 3. `taxonomy.php` 4. `archive.php` 5. `index.php` Custom Post Type Archive: 1. `archive-{post-type}.php` (e.g., `archive-property.php`) 2. `archive.php` 3. `index.php` Search Results: 1. `search.php` 2. `index.php` 404 Page: 1. `404.php` 2. `index.php` The full hierarchy is more detailed than this summary, covering attachments, embeds, author archives, date archives, and private pages. The WordPress Developer Handbook maintains the complete visual flow chart.
§ 3 Block Theme Template Hierarchy
With the introduction of Full Site Editing (FSE) and block themes, the template hierarchy has evolved. Block themes use HTML files with block markup instead of PHP template files. The hierarchy logic is the same, but: - Templates are stored in `/wp-content/themes/{theme}/templates/` instead of the theme root. - Files use `.html` extension instead of `.php`. - Content is rendered using blocks, not PHP template tags. - Templates are editable through the Site Editor (visual interface) and are saved to the database, overriding the theme files. The same fallback order applies. A block theme needs at minimum `templates/index.html` as the catch-all fallback. If `templates/single.html` doesn't exist for a single post, WordPress falls back to `templates/index.html`. The hierarchy is simpler in block themes because many template types (embed, attachment) are less relevant to the block editing paradigm. But the core routing logic is unchanged: most specific to least specific, `index.html` as the final fallback.
§ 4 Practical Template Hierarchy Examples
Example 1: Blog with featured posts. You want the first post on your blog to display differently from the rest. Create `single-post-{slug}.php` for that specific post. All other posts use `single.php`. Example 2: Portfolio CPT with multiple layouts. Your 'portfolio' CPT has projects in 'web' and 'graphic-design' categories. Create `single-portfolio.php` for all portfolio items, then use `category-web.php` and `category-graphic-design.php` to give each category archive its own layout. Example 3: Landing page design. Client wants the 'About Us' page to look completely different from other pages. Create `pagename-about-us.php` with a custom layout. All other pages use `page.php`. The hierarchy eliminates the need for complex conditional logic (`if (is_single() && 'product' == get_post_type())`) in your template files. Each template file handles one specific case. The hierarchy routes the request.
§ 5 Common questions
- Q. Do block themes use the same template hierarchy?
- A. Yes. The template hierarchy logic is identical. Block themes use .html files in a /templates/ directory, but the priority order and fallback system are the same.
- Q. What happens if no template file matches?
- A. WordPress falls back to index.php (classic themes) or templates/index.html (block themes). Every theme must have at least index.php as a safety net.
- Q. Can I override the hierarchy with plugins?
- A. Yes. The template_include and template_redirect filters let you modify the hierarchy programmatically. This is useful for complex routing rules.
- The Template Hierarchy maps URL requests to theme template files, cascading from most specific to index.php as the final fallback.
- It enables custom layouts for specific posts, pages, categories, custom post types, and taxonomies without conditional PHP logic.
- Block themes use .html files in /templates/ with the same hierarchy logic as classic .php themes.
- Understanding the hierarchy is essential for efficient WordPress theme development.
We build WordPress themes that leverage the template hierarchy for clean, maintainable code. Custom template structures for CPTs, taxonomy archives, and landing pages without bloat. Get in touch about your WordPress theme project.
Get in touchThe WordPress Template Hierarchy is the system that determines which PHP template file is used to render a given page request. It follows a specific order of precedence, starting with the most specific template file (like single-post.php) and falling back to less specific files (like index.php) when more specific ones don't exist.
Category: Cms (also: Software Engineering)
Author: Atomic Glue Editorial Team
## Definition
The Template Hierarchy is WordPress's built-in system for mapping URL requests to theme template files. When a visitor requests a URL, WordPress analyzes the request type (home page, single post, archive page, search results, etc.) and selects the most specific template file available in the active theme. The hierarchy is a cascading fallback system. WordPress starts with the most specific template file that matches the request and moves down the chain until it finds a file that exists. If no matching template exists at any level, it falls back to `index.php`, which is the only required file in any WordPress theme. Understanding the template hierarchy is essential for WordPress theme development. It lets you create custom layouts for different content types without writing complex conditional logic. A `single-product.php` file automatically renders single product pages. A `category-videos.php` file automatically renders the 'Videos' category archive. The hierarchy handles the routing.
## The Hierarchy in Detail
Here's how WordPress resolves template files for common request types, in order of priority (most specific first): **Home/Front Page:** 1. `front-page.php` 2. `home.php` 3. `index.php` **Single Post:** 1. `single-{post-type}-{slug}.php` (e.g., `single-post-hello-world.php`) 2. `single-{post-type}.php` (e.g., `single-post.php` or `single-product.php`) 3. `single.php` 4. `singular.php` 5. `index.php` **Page:** 1. `pagename-{slug}.php` (e.g., `pagename-about-us.php`) 2. `page-{id}.php` (e.g., `page-42.php`) 3. `page.php` 4. `singular.php` 5. `index.php` **Category Archive:** 1. `category-{slug}.php` (e.g., `category-news.php`) 2. `category-{id}.php` (e.g., `category-5.php`) 3. `category.php` 4. `archive.php` 5. `index.php` **Tag Archive:** 1. `tag-{slug}.php` (e.g., `tag-wordpress.php`) 2. `tag-{id}.php` 3. `tag.php` 4. `archive.php` 5. `index.php` **Custom Taxonomy Archive:** 1. `taxonomy-{taxonomy}-{term}.php` (e.g., `taxonomy-genre-science-fiction.php`) 2. `taxonomy-{taxonomy}.php` (e.g., `taxonomy-genre.php`) 3. `taxonomy.php` 4. `archive.php` 5. `index.php` **Custom Post Type Archive:** 1. `archive-{post-type}.php` (e.g., `archive-property.php`) 2. `archive.php` 3. `index.php` **Search Results:** 1. `search.php` 2. `index.php` **404 Page:** 1. `404.php` 2. `index.php` The full hierarchy is more detailed than this summary, covering attachments, embeds, author archives, date archives, and private pages. The WordPress Developer Handbook maintains the complete visual flow chart.
## Block Theme Template Hierarchy
With the introduction of [Full Site Editing (FSE)](/glossary/full-site-editing-fse) and block themes, the template hierarchy has evolved. Block themes use HTML files with block markup instead of PHP template files. The hierarchy logic is the same, but: - Templates are stored in `/wp-content/themes/{theme}/templates/` instead of the theme root. - Files use `.html` extension instead of `.php`. - Content is rendered using blocks, not PHP template tags. - Templates are editable through the Site Editor (visual interface) and are saved to the database, overriding the theme files. The same fallback order applies. A block theme needs at minimum `templates/index.html` as the catch-all fallback. If `templates/single.html` doesn't exist for a single post, WordPress falls back to `templates/index.html`. The hierarchy is simpler in block themes because many template types (embed, attachment) are less relevant to the block editing paradigm. But the core routing logic is unchanged: most specific to least specific, `index.html` as the final fallback.
## Practical Template Hierarchy Examples
**Example 1: Blog with featured posts.** You want the first post on your blog to display differently from the rest. Create `single-post-{slug}.php` for that specific post. All other posts use `single.php`. **Example 2: Portfolio CPT with multiple layouts.** Your 'portfolio' CPT has projects in 'web' and 'graphic-design' categories. Create `single-portfolio.php` for all portfolio items, then use `category-web.php` and `category-graphic-design.php` to give each category archive its own layout. **Example 3: Landing page design.** Client wants the 'About Us' page to look completely different from other pages. Create `pagename-about-us.php` with a custom layout. All other pages use `page.php`. The hierarchy eliminates the need for complex conditional logic (`if (is_single() && 'product' == get_post_type())`) in your template files. Each template file handles one specific case. The hierarchy routes the request.
## Common questions
Q: Do block themes use the same template hierarchy?
A: Yes. The template hierarchy logic is identical. Block themes use .html files in a /templates/ directory, but the priority order and fallback system are the same.
Q: What happens if no template file matches?
A: WordPress falls back to index.php (classic themes) or templates/index.html (block themes). Every theme must have at least index.php as a safety net.
Q: Can I override the hierarchy with plugins?
A: Yes. The template_include and template_redirect filters let you modify the hierarchy programmatically. This is useful for complex routing rules.
## Key takeaways
- The Template Hierarchy maps URL requests to theme template files, cascading from most specific to index.php as the final fallback.
- It enables custom layouts for specific posts, pages, categories, custom post types, and taxonomies without conditional PHP logic.
- Block themes use .html files in /templates/ with the same hierarchy logic as classic .php themes.
- Understanding the hierarchy is essential for efficient WordPress theme development.
## Related entries
- [WordPress](atomicglue.co/glossary/wordpress)
- [Themes](atomicglue.co/glossary/themes)
- [Custom Post Types](atomicglue.co/glossary/custom-post-types)
- [Taxonomies](atomicglue.co/glossary/taxonomies)
- [Full Site Editing (FSE)](atomicglue.co/glossary/full-site-editing-fse)
Last updated July 2025. Permalink: atomicglue.co/glossary/template-hierarchy