The template hierarchy is WordPress’s decision engine for page routing. Every time a visitor loads a URL, WordPress walks through a prioritized list of template files to determine which one renders the page. In block themes, this system works with HTML files in the templates directory instead of PHP files, but the resolution logic is identical to classic themes. Understanding the template hierarchy at a deep level is essential for any theme developer because it determines how every single page on a WordPress site gets rendered — from the homepage to individual posts, category archives, author pages, search results, and 404 errors. This guide covers the complete template hierarchy for block themes, including resolution chains for every content type, custom templates, template parts, debugging strategies, and advanced patterns for complex site architectures.
How the Template Hierarchy Works in Block Themes
When a visitor requests a URL, WordPress first determines the type of content being requested — is it a single post, a page, a category archive, a search result, or something else? Once WordPress identifies the content type, it walks through a specific chain of template filenames, checking your theme’s templates directory for each one. The first match wins and gets used to render the page.
In classic themes, these templates were PHP files (single.php, page.php, archive.php). In block themes, they are HTML files containing block markup (single.html, page.html, archive.html). The resolution logic is exactly the same — only the file extension and content format changed. This means everything you know about the classic template hierarchy applies directly to block themes.
The hierarchy always ends with index.html as the ultimate fallback. If no other template matches the requested content type, WordPress uses index.html. This is why every block theme must include an index.html file — it is the safety net that ensures every page on your site gets rendered, even if you have not created a specific template for that content type.
WordPress also checks the database before checking theme files. If a user has created or modified a template through the Site Editor (Appearance → Editor → Templates), that database version takes priority over the theme file. This means users can customize any template without modifying theme files, and their changes persist through theme updates. The resolution order is: database template → theme file template → parent theme file template (for child themes) → index.html fallback.
Complete Template Resolution Chains
Below is the complete resolution chain for every major content type in WordPress. For each type, WordPress checks templates from left to right, using the first one it finds.
Single Posts
When a visitor views an individual blog post, WordPress checks: single-post-{slug}.html → single-post.html → single.html → singular.html → index.html. The slug-specific template lets you create a completely unique layout for a specific post. For example, single-post-welcome.html would only apply to the post with the slug “welcome”. The single-post.html template applies to all posts of the default “post” type, while single.html applies to all singular content including custom post types.
Pages
For static pages: page-{slug}.html → page-{id}.html → page.html → singular.html → index.html. Pages support both slug-based and ID-based specific templates. The slug-based approach (page-about.html) is preferred because slugs are human-readable and survive database migrations. ID-based templates (page-42.html) are fragile because post IDs change between environments.
Custom Post Types
For registered custom post types: single-{post-type}-{slug}.html → single-{post-type}.html → single.html → singular.html → index.html. If you register a “portfolio” post type, WordPress checks single-portfolio-{slug}.html first, then single-portfolio.html. This is critical for theme developers who need to provide distinct layouts for different content types — a portfolio item typically needs a different layout than a blog post.
Category Archives
For category archive pages: category-{slug}.html → category-{id}.html → category.html → archive.html → index.html. The category-specific template lets you create unique layouts for individual categories. A theme for a news site might have category-sports.html with a different grid layout than category-opinion.html.
Tag Archives
For tag archive pages: tag-{slug}.html → tag-{id}.html → tag.html → archive.html → index.html. Tags follow the same pattern as categories, giving you granular control over how tagged content collections are displayed.
Custom Taxonomy Archives
For custom taxonomy archives: taxonomy-{taxonomy}-{term}.html → taxonomy-{taxonomy}.html → taxonomy.html → archive.html → index.html. If you register a “genre” taxonomy, WordPress checks taxonomy-genre-fiction.html for the “fiction” term, then taxonomy-genre.html for all genre archives.
Author Archives
For author pages: author-{nicename}.html → author-{id}.html → author.html → archive.html → index.html. Author-specific templates are useful for multi-author sites where different authors might have different page layouts — for example, a featured columnist versus a guest contributor.
Date Archives
For date-based archives: date.html → archive.html → index.html. Date archives are simpler than other archive types because there are no slug-specific or ID-specific variants. The date.html template handles year, month, and day archives.
Search Results
For search result pages: search.html → index.html. Search has the simplest hierarchy — either you have a search.html template or WordPress falls back to index.html. Most themes should include a dedicated search.html template because search results need a different layout than regular content.
404 Error Pages
For pages not found: 404.html → index.html. A custom 404.html template is important for user experience. It should include a search form, links to popular content, and a clear message explaining that the page was not found. Without 404.html, your 404 page renders with index.html, which displays normal content queries — confusing for visitors.
Homepage
The homepage has a special hierarchy that depends on your Reading Settings. If set to display latest posts: home.html → index.html. If set to a static page: the page hierarchy applies (page-{slug}.html → page.html → singular.html). The front-page.html template overrides both settings — if it exists, it always renders the homepage regardless of Reading Settings configuration.
Template Parts: Reusable Layout Components
Template parts live in the parts directory and represent reusable sections that multiple templates share. The most common template parts are header.html and footer.html, but you can create parts for any repeating section — sidebars, comment sections, post meta displays, call-to-action sections, or newsletter signup forms.
Template parts are included in templates using the Template Part block markup. The block references a part by its slug attribute, which maps to the filename in the parts directory. Change a template part once, and every template that includes it updates automatically.
You register template parts in theme.json under the templateParts array. Each entry specifies the part’s name, title (displayed in the Site Editor), and area (header, footer, or uncategorized). The area property tells the Site Editor where to display the part in the template editing interface and determines the HTML element wrapper — header parts get a header element, footer parts get a footer element.
For detailed guidance on building and styling header and footer template parts including layout patterns, responsive strategies, and navigation integration, see our header and footer template parts guide.
Creating Custom Templates
Block themes can register custom templates that users assign to specific pages or posts. Custom templates appear in the page editor’s Template selector, letting users choose a different layout without any code. This is one of the most user-friendly features of block themes.
Register custom templates in theme.json under the customTemplates array. Each entry needs a name (matching the filename without extension), title (displayed to users), and postTypes array (which content types can use this template).
Common custom templates that production themes should include:
- Full Width (no sidebar): A single-column layout that spans the full content width. Useful for landing pages, portfolio pieces, and content that benefits from maximum horizontal space.
- Blank Canvas: A template with no header, footer, or sidebars — just the content area. Perfect for standalone landing pages, sales pages, or coming-soon pages that should not show site navigation.
- Sidebar Right / Sidebar Left: Templates with a sidebar on either side. Even though block themes can handle sidebars through column blocks within any template, having dedicated sidebar templates is more intuitive for users.
- Wide Content: A template with a wider content area than the default, useful for pages with tables, comparison charts, or image galleries that need more horizontal space.
The filename must match the name property in theme.json. If you register a template with name “page-full-width”, the file must be templates/page-full-width.html. WordPress will not find the template if the naming does not match exactly.
Site Editor Templates vs Theme File Templates
One of the most important concepts in block theme development is understanding the relationship between templates stored in theme files and templates created or modified through the Site Editor. They coexist in a specific priority order that affects how themes update and how users customize their sites.
Theme file templates live in your theme’s templates directory and ship with your theme. They provide the default layouts for your theme. Site Editor templates are stored in the WordPress database as wp_template posts. When a user modifies a template through the Site Editor, WordPress saves a copy in the database.
The database version always takes priority over the theme file version. This means user customizations survive theme updates — WordPress continues using the database template even after you ship a new version of the theme file template. Users can reset a modified template back to the theme file version through the Site Editor’s “Clear customizations” option.
This architecture has implications for theme developers. When you update a template in your theme, existing users who have not modified that template get the update automatically. But users who have customized the template through the Site Editor will not see your changes because their database version takes priority. Document important template changes in your changelog so users know when to consider resetting their customizations to get new features.
Debugging the Template Hierarchy
When a page does not render with the template you expect, debugging the hierarchy is essential. Several tools and techniques help identify which template WordPress is actually using.
Query Monitor plugin is the most powerful debugging tool for the template hierarchy. Its Templates panel shows exactly which template file or database template is rendering the current page, which template parts are included, and the complete list of templates WordPress checked before finding a match. Install Query Monitor on your development site and keep it active during theme development.
The Site Editor template list (Appearance → Editor → Templates) shows all available templates, including both theme file templates and user-modified database templates. Database templates show a “Customized” badge. This view helps you identify when a database template is overriding your theme file template.
Template debugging in functions.php can help during development. The template_include filter fires after WordPress resolves the template hierarchy and lets you log or display the resolved template path. Add a temporary filter that outputs the template filename as an HTML comment for debugging, and remove it before deploying to production.
Common debugging scenarios and their solutions:
- Template not being used: Check the filename spelling and location. Templates must be in the templates directory (not the theme root). Filenames are case-sensitive on Linux servers.
- Database template overriding theme file: Check the Site Editor for customized templates. Reset customizations if you need the theme file version to apply.
- Child theme template not overriding parent: Child theme templates take priority over parent theme templates, but database templates take priority over both. Check the Site Editor first.
- Custom post type template not found: Verify the post type slug matches the filename. If the post type is “portfolio”, the template must be single-portfolio.html — not single-Portfolio.html or single_portfolio.html.
Advanced Template Patterns
Conditional Content Within Templates
Block themes are declarative by design — templates are static HTML with block markup. But some sites need conditional logic within templates, such as showing different content for logged-in versus logged-out users, or displaying seasonal promotions. You can achieve this by registering block patterns with PHP callbacks that include conditional logic. The pattern is included in the template, and the PHP callback determines what content to render based on runtime conditions.
Template Hierarchy for WooCommerce
WooCommerce adds its own templates to the hierarchy. Product pages use single-product.html, the shop page uses archive-product.html, and product category pages use taxonomy-product_cat-{slug}.html. WooCommerce block themes need these templates to provide proper layouts for store pages. If your theme does not include WooCommerce-specific templates, the fallback chain applies — product pages fall back to single.html, which may not provide the layout WooCommerce needs for proper product display.
Template Hierarchy for BuddyPress and bbPress
Community plugins like BuddyPress and bbPress register custom post types and pages that need specific template handling. BuddyPress member profiles, group pages, and activity streams each look for their own template files. When building a theme that supports these plugins, create dedicated templates for their content types or ensure your fallback templates (single.html, archive.html) handle the plugins’ output gracefully.
Performance Implications of Template Architecture
The number and complexity of your templates affect your theme’s performance, though the impact is different from classic PHP themes. In block themes, template rendering happens through the block parser, which processes the HTML block markup and renders each block. More blocks in a template means more parsing and rendering work.
Keep your templates lean. Every block in a template adds processing overhead. Use template parts to avoid duplicating block markup across templates. If ten templates each include the same header and footer, those blocks are defined once in the template parts rather than repeated ten times in ten template files.
The template resolution process itself is fast — WordPress checks for file existence using the filesystem, which is a negligible operation. The performance difference between having five templates and fifty templates is unmeasurable. Focus optimization efforts on the content of your templates (reducing block count, optimizing queries in Query Loop blocks) rather than the number of template files.
For a deeper understanding of the block theme architecture that underpins the template system, including theme.json configuration, Block Hooks, and the Interactivity API, see our block theme development guide.
Template Hierarchy Best Practices
- Always include index.html. It is the required fallback for every content type. Without it, your theme is technically invalid and may not activate on some WordPress installations.
- Be specific only when the layout genuinely differs. Do not create category-specific templates unless those categories actually need different layouts. Fewer templates means easier maintenance and fewer places to update when you change your design.
- Use template parts for every repeated section. Headers, footers, sidebars, post meta displays — anything that appears in more than one template should be a template part. This follows the DRY principle and ensures consistency across your theme.
- Register custom templates in theme.json. Always register custom templates with descriptive titles so users can easily identify them in the page editor. Include a postTypes array to restrict templates to appropriate content types — a “Product Showcase” template should only be available for product pages, not blog posts.
- Test the complete hierarchy. During development, visit every content type on your site — homepage, single posts, pages, categories, tags, authors, search, 404 — and verify the correct template renders. Use Query Monitor to confirm.
- Document your template architecture. Create a page in your theme documentation that lists all available templates, their purposes, and which content types they apply to. Users who understand your template architecture will make better use of your theme and submit fewer support requests.
- Consider child theme compatibility. If users might create child themes from your theme, ensure your template hierarchy is clean and predictable. Avoid unusual template naming that could confuse child theme developers.
Migrating Template Hierarchy Knowledge from Classic to Block Themes
If you are transitioning from classic theme development, the template hierarchy in block themes will feel familiar because the resolution logic is identical. The differences are entirely in file format and content.
Classic PHP templates contained a mix of PHP logic, HTML output, WordPress template tags (the_title, the_content, the_post_thumbnail), and conditional functions (is_single, is_page, is_category). Block theme templates contain pure block markup in HTML files — no PHP, no template tags, no conditional logic.
The equivalent of template tags in block themes are blocks. Where classic themes used the_title() in PHP, block themes use the Post Title block. Where classic themes used the_content(), block themes use the Post Content block. Where classic themes used get_header() and get_footer(), block themes use Template Part blocks. The mapping is direct, and once you understand it, converting your mental model from classic to block themes is straightforward.
The one significant addition in block themes is the Site Editor override system. Classic themes had no built-in way for users to modify templates without editing PHP files. Block themes allow users to customize any template through the visual Site Editor, with those customizations stored in the database and taking priority over theme files. This changes how you think about template ownership — your theme files are defaults, not final output. For a comprehensive migration walkthrough, see our classic to block theme migration guide.
Frequently Asked Questions
What happens if I delete a template from my theme files?
If you remove a template file from your theme, WordPress falls through to the next template in the hierarchy chain. If a user had customized that template through the Site Editor, the database version continues to work because it does not depend on the theme file. However, if the user later resets their customizations, the template will no longer exist and WordPress will fall through to the next match in the hierarchy. Always update your changelog when removing templates so users are aware of the change.
Can I create templates for specific post formats?
WordPress does not include post format-specific templates in the default hierarchy. There is no single-post-format-video.html resolution step. However, you can work around this by creating custom templates and registering them for posts. Users manually assign the template to individual posts through the editor. Alternatively, use block patterns that provide format-specific layouts users can insert into the default template.
How do I prevent users from modifying certain templates?
You cannot prevent users from customizing templates through the Site Editor — this is by design in WordPress. However, you can use theme.json settings to restrict which blocks and customization options are available within templates. Limiting color options, disabling custom font sizes, or restricting available blocks gives you control over the design boundaries while still allowing users to make content changes.
Does the template hierarchy work differently in multisite?
The template hierarchy works identically in WordPress multisite installations. Each site in the network resolves templates independently based on its active theme and any Site Editor customizations stored in that site’s database. Network-activated themes provide the same template files to all sites, but each site can have its own Site Editor customizations. There is no network-level template override mechanism.
How do I handle templates for custom archive pages with multiple post types?
WordPress does not provide a built-in template for mixed post type archives. The archive.html template handles all archive types, but if you need a custom layout for an archive that displays multiple post types, create a custom template and use the Query Loop block with specific post type filters. Alternatively, use the archive.html template with conditional block patterns that adjust the layout based on the queried post type using PHP-backed pattern callbacks.
Summary
The template hierarchy is the routing engine of every WordPress site, and mastering it in block themes is non-negotiable for theme developers. The resolution chains are identical to classic themes, but block themes add the Site Editor override layer and replace PHP templates with HTML block markup. Build your themes with a clean, minimal set of templates that cover each content type your theme supports. Use template parts for every repeated section, register custom templates with clear names in theme.json, and test the complete hierarchy with Query Monitor during development. A well-structured template architecture makes your theme predictable for users, maintainable for you, and extensible for anyone building child themes on top of your work.