WordPress block themes give you full control over how every page type renders, but only if you know how to override core templates. In the Site Editor, you can create custom archive pages, single post layouts, 404 templates, search results pages, and more without touching PHP. This guide covers every core template override available in block themes, with practical examples and debugging strategies for each.

Understanding the Template Resolution Order

Before overriding templates, you need to understand how WordPress resolves which template to use. The system checks for the most specific template first, then falls back to more general ones. This is the template hierarchy, and it works identically in block themes as in classic themes, except templates are stored as HTML block markup in a templates/ directory instead of PHP files.

For a single post, WordPress checks in this order:

  • single-{post-type}-{slug}.html, most specific
  • single-{post-type}.html
  • single.html
  • singular.html
  • index.html, fallback

For category archives: category-{slug}.html → category-{ID}.html → category.html → archive.html → index.html.

Understanding this cascade is critical. If you create category.html but want a specific category to look different, you create category-{slug}.html alongside it. WordPress picks the most specific match automatically, you never need conditional PHP logic to route between templates.

How Block Theme Template Overrides Are Stored

Block themes have two layers of templates: the files shipped in your theme directory and the overrides stored in the database. When you edit a template in the Site Editor, WordPress stores your changes in the wp_posts table with a post type of wp_template. These database records take precedence over theme files.

This layered system means:

  • Theme files are your defaults, what new sites using your theme get out of the box
  • Database overrides are per-site customisations, they survive theme updates but don’t transfer to other sites
  • Export syncs database overrides back into theme files, letting you distribute customisations

When you go to Appearance → Editor → Templates, any template with a pencil icon has a database override. Templates without it are served directly from your theme files.

Creating a Custom Single Post Template

The most common override is a custom single.html template. You can create this directly in the Site Editor without any file system access.

Via the Site Editor

  1. Go to Appearance → Editor
  2. Click Templates in the left sidebar
  3. Click the + button to add a new template
  4. Select Single item: Posts
  5. Build your layout using blocks
  6. Save

WordPress saves this as templates/single.html in your theme’s database override (or directly in your theme files if you export them). The template is immediately active for all single posts.

Via Theme Files

To ship a custom single template in your theme, create templates/single.html with block markup:

<!-- wp:template-part {"slug":"header","area":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
  <!-- wp:post-title {"level":1} /-->
  <!-- wp:post-featured-image /-->
  <!-- wp:post-content /-->
  <!-- wp:post-terms {"term":"category"} /-->
  <!-- wp:post-terms {"term":"post_tag"} /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","area":"footer"} /-->

Post Type Specific Single Templates

If you want different single layouts for different post types, create type-specific templates. For a custom post type called case_study, create templates/single-case_study.html. For a specific post slug like our-story, create templates/single-post-our-story.html.

This granular control is particularly useful for product-style CPTs where each entry needs a completely different layout than standard blog posts, without requiring any PHP routing logic.

Overriding Archive Templates

Archive templates control how post lists render for categories, tags, authors, and date-based archives. A single archive.html serves as the catch-all, but you can override each type specifically for precise control over layout and content.

Category Archive Template

Create templates/category.html for all category archives, or templates/category-{slug}.html for a specific category. The slug-specific version is ideal when one category needs a dramatically different layout, say, a magazine-style grid for a photography category versus a simple list for everything else.

<!-- wp:template-part {"slug":"header","area":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
  <!-- wp:query-title {"type":"archive"} /-->
  <!-- wp:term-description /-->

  <!-- wp:query {"queryId":1,"query":{"perPage":10,"inherit":true}} -->
  <div class="wp-block-query">
    <!-- wp:post-template -->
      <!-- wp:post-title {"isLink":true} /-->
      <!-- wp:post-date /-->
      <!-- wp:post-excerpt /-->
    <!-- /wp:post-template -->
    <!-- wp:query-pagination /-->
  </div>
  <!-- /wp:query -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","area":"footer"} /-->

Key blocks for archive templates:

  • Query Title (wp:query-title), displays the archive name automatically
  • Term Description (wp:term-description), shows the category or tag description if one has been set
  • Query Loop with "inherit":true, respects the current archive context without any manual filtering

Tag Archive Template

Create templates/tag.html or templates/tag-{slug}.html for tag-specific overrides. The structure mirrors the category template, use the same Query Loop with "inherit":true so WordPress automatically filters by the current tag without any additional configuration.

One practical use case: if your site uses tags as content series identifiers, you could give the tag archive a series-style layout that shows posts in a numbered sequence, while your general category archives use a standard blog list.

Author Archive Template

Author archives let you showcase a writer’s posts alongside their bio. Create templates/author.html with an avatar and biography block at the top:

<!-- wp:template-part {"slug":"header","area":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
  <!-- wp:columns -->
  <div class="wp-block-columns">
    <!-- wp:column {"width":"20%"} -->
    <div class="wp-block-column">
      <!-- wp:avatar {"size":96} /-->
    </div>
    <!-- /wp:column -->
    <!-- wp:column {"width":"80%"} -->
    <div class="wp-block-column">
      <!-- wp:query-title {"type":"archive"} /-->
      <!-- wp:post-author-biography /-->
    </div>
    <!-- /wp:column -->
  </div>
  <!-- /wp:columns -->

  <!-- wp:query {"queryId":1,"query":{"perPage":10,"inherit":true}} -->
  <!-- ... post list ... -->
  <!-- /wp:query -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","area":"footer"} /-->

For per-author templates, use templates/author-{nicename}.html where nicename is the author’s URL-safe username. This is useful when a featured contributor, such as a well-known industry expert, needs a completely custom profile layout with a larger bio, social links, and a highlight grid of their best work.

Date Archive Templates

Date archives are less common on modern sites, but WordPress generates them automatically. The block theme hierarchy supports:

  • templates/date.html, covers year, month, and day archives
  • No slug-specific variants exist for date archives (dates aren’t slugs)

Use the Query Title block with "type":"archive", WordPress outputs “January 2026”, “2026”, or “March 15, 2026” automatically depending on the archive granularity. Pair it with a Query Loop using "inherit":true and the date filtering happens automatically.

Custom 404 Template

A well-designed 404 page can recover visitors who land on broken URLs. Create templates/404.html, this is one of the few templates where you can’t rely on any post-related blocks, since there’s no post in context:

<!-- wp:template-part {"slug":"header","area":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
  <!-- wp:heading {"level":1} -->
  <h1>Page Not Found</h1>
  <!-- /wp:heading -->

  <!-- wp:paragraph -->
  <p>The page you're looking for doesn't exist or has been moved.</p>
  <!-- /wp:paragraph -->

  <!-- wp:search {"label":"Search","buttonText":"Search"} /-->

  <!-- wp:heading {"level":2} -->
  <h2>Popular Posts</h2>
  <!-- /wp:heading -->

  <!-- wp:query {"queryId":2,"query":{"perPage":5,"inherit":false,"orderby":"comment_count"}} -->
  <div class="wp-block-query">
    <!-- wp:post-template -->
      <!-- wp:post-title {"isLink":true} /-->
    <!-- /wp:post-template -->
  </div>
  <!-- /wp:query -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","area":"footer"} /-->

Notice the Query Loop here uses "inherit":false because there’s no archive context to inherit. You specify the query manually, popular posts by comment count is a common choice. You can also add a list of main category links to give visitors clear navigation paths.

Search Results Template

Create templates/search.html to customise the search results page. This is one of the templates where "inherit":true on the Query Loop automatically applies the search filter from the URL:

<!-- wp:template-part {"slug":"header","area":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
  <!-- wp:query-title {"type":"search"} /-->

  <!-- wp:query {"queryId":1,"query":{"perPage":10,"inherit":true}} -->
  <div class="wp-block-query">
    <!-- wp:post-template -->
      <!-- wp:post-title {"isLink":true} /-->
      <!-- wp:post-excerpt {"moreText":"Read more"} /-->
    <!-- /wp:post-template -->

    <!-- wp:query-no-results -->
      <!-- wp:paragraph -->
      <p>No results found. Try a different search term or browse by category.</p>
      <!-- /wp:paragraph -->
      <!-- wp:search {"label":"Try again","buttonText":"Search"} /-->
    <!-- /wp:query-no-results -->

    <!-- wp:query-pagination /-->
  </div>
  <!-- /wp:query -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","area":"footer"} /-->

Always include the Query No Results block (wp:query-no-results), it displays only when nothing matches the search term. Adding a second search form inside it improves UX significantly by letting users refine their query without scrolling back up.

Custom Post Type Templates

Block themes fully support custom post types in the template hierarchy. If you have a CPT with the slug product, here are the templates WordPress will look for:

  • single-product.html, all product single pages
  • single-product-{slug}.html, one specific product
  • archive-product.html, the product archive listing

You can create these via the Site Editor by going to Templates → Add New Template → Custom Template and selecting the post type. The Site Editor presents a dropdown of all registered public CPTs, making it straightforward to target specific types without memorising file naming conventions.

For the archive template, the Query Loop with "inherit":true automatically filters to the CPT when the archive URL is visited. You don’t need to specify post_type in the query block attributes.

Working with Hierarchical Taxonomies

WordPress supports hierarchical taxonomies (like categories) where terms can have parent-child relationships. The template hierarchy handles this at the term level, not the hierarchy level, meaning category-{slug}.html applies to that specific term regardless of whether it’s a parent or child category.

If you want parent and child categories to share a layout but need to display the breadcrumb trail differently, handle that with a template part rather than separate templates. Create a category-breadcrumb.html template part and reference it from your category.html, then use dynamic blocks or the Breadcrumbs block to output the correct trail automatically.

Reusing Template Parts Across Overrides

Template parts eliminate duplication across every template override. Instead of repeating your header and footer markup in every template file, reference them once with a single line:

<!-- wp:template-part {"slug":"header","area":"header"} /-->
<!-- wp:template-part {"slug":"footer","area":"footer"} /-->

Beyond headers and footers, you can build content-specific template parts that multiple templates share. For example:

  • post-meta.html, date, author, categories, read time; used in both single.html and single-post-type.html
  • archive-header.html, query title and term description; used in category.html, tag.html, and author.html
  • post-card.html, a card layout for post listings; referenced inside Query Loop post templates

To create a reusable template part: go to Editor → Template Parts → Add New, name your part, assign it to an area (General, Header, Footer, or Sidebar), then build the content. Reference it from any template with wp:template-part {"slug":"your-part-name"}. See the full template parts guide for more detail.

Site Editor vs Theme Files: Which to Use

Template overrides created in the Site Editor are stored in the database and take precedence over theme files. Here’s when to use each approach:

  • Theme files, ship your default templates with the theme for distribution; these are the fallback for every new site activating your theme
  • Site Editor overrides, site-specific customisations that don’t need to ship with the theme; survive theme updates but are scoped to this installation
  • Export workflow, use Editor → Export to bundle Site Editor changes back into theme files for distribution or version control

For agency work and client themes, a clean workflow is to develop templates in the Site Editor for rapid iteration, export to theme files when ready, then version-control the exported files. This gives you the visual editing ergonomics of the Site Editor with the reliability of code-based templates.

Debugging Template Resolution

When a page isn’t using the template you expect, use these debugging approaches in order:

  • Query Monitor plugin, shows the active template file under the Template tab; the most reliable way to see exactly what WordPress resolved
  • Site Editor → Templates, lists all templates including database overrides; check for unexpected overrides here before looking at files
  • Check capitalisation, template filenames are case-sensitive on Linux servers; Category.html won’t match when WordPress looks for category.html
  • Check the slug, for category-{slug}.html, verify the slug in Settings → Categories matches exactly
  • Clear cache, page cache can serve the old template after changes; flush all cache layers (server, plugin, CDN) before testing

One subtle issue: if you have both a theme file and a Site Editor override for the same template, the Site Editor version always wins. If you’ve updated your theme file and don’t see the change, check whether a database override exists and clear it with Clear customisations.

Block theme template hierarchy diagram showing resolution order for single, archive, 404 and search templates
The block theme template hierarchy, WordPress checks for the most specific template first and falls back to more general ones.

Complete Template Override Reference

Page TypeMost Specific TemplateFallback Chain
Single postsingle-post-{slug}.htmlsingle.html → singular.html → index.html
Single pagepage-{slug}.htmlpage-{ID}.html → page.html → singular.html → index.html
Single CPTsingle-{cpt}-{slug}.htmlsingle-{cpt}.html → single.html → index.html
Category archivecategory-{slug}.htmlcategory-{ID}.html → category.html → archive.html → index.html
Tag archivetag-{slug}.htmltag-{ID}.html → tag.html → archive.html → index.html
Custom taxonomytaxonomy-{tax}-{slug}.htmltaxonomy-{tax}.html → taxonomy.html → archive.html → index.html
Author archiveauthor-{nicename}.htmlauthor-{ID}.html → author.html → archive.html → index.html
Date archivedate.htmlarchive.html → index.html
CPT archivearchive-{cpt}.htmlarchive.html → index.html
Search resultssearch.htmlindex.html
404 page404.htmlindex.html
Front page (static)front-page.htmlpage.html → singular.html → index.html
Blog homehome.htmlindex.html

Frequently Asked Questions

Can I override templates without editing theme files?

Yes. Any template created or modified in the Site Editor is stored in the database and overrides the theme file version automatically. No FTP or code editor access required.

Do template overrides survive theme updates?

Site Editor overrides (stored in the database) survive theme updates. Template files inside the theme directory will be overwritten on update, use a child theme or rely on Site Editor overrides for customisations you want to persist.

How do I reset a template to the theme default?

In the Site Editor, open the template and click the three-dot menu → Clear customisations. This deletes the database override and restores the theme file version. If no theme file exists for that template, WordPress falls back to the next template in the hierarchy.

Can I use PHP in block theme templates?

No. Block theme templates are pure HTML block markup, PHP is not executed in template files. For dynamic functionality, use server-rendered blocks like Query Loop, dynamic blocks registered with render_callback, or the Interactivity API for client-side state. See the template hierarchy guide for more on dynamic routing.

What happens if I delete a template override?

WordPress falls back to the next template in the hierarchy automatically. Deleting category.html means category archives fall through to archive.html. If that doesn’t exist either, they use index.html. Nothing breaks, the fallback chain always has index.html as the final safety net.

Can I assign a template to a specific post from the editor?

Yes. In the post editor, open the Page panel in the sidebar and look for the Template dropdown. Any template you’ve created appears here and can be assigned to that specific post or page, overriding the hierarchy resolution for that entry.

Advanced Template Techniques for Agencies and Developers

Once you are comfortable with the core template hierarchy, several advanced patterns unlock significant workflow improvements, especially when managing multiple client sites or distributing themes to a wider audience.

Child Themes and Template Inheritance

Child themes in block themes work exactly as they do in classic themes, but the override applies to template files rather than PHP files. Create a child theme with a style.css declaring the parent via Template: parent-theme-slug, then add a /templates/ folder containing only the templates you need to override. WordPress checks the child theme’s templates folder first, then the parent theme’s, giving you a clean separation between the distributable parent and the client-specific child.

This pattern is particularly powerful for agencies: ship a polished parent theme to every client, then maintain a lightweight child theme per client with site-specific template overrides. When you update the parent, client customisations are preserved automatically. The child theme approach also makes version control straightforward, client-specific changes live in their own repository, completely separate from the shared theme codebase.

Template Locking for Editorial Teams

Block themes support template locking, which prevents editors from accidentally breaking critical layout regions. You can lock specific blocks within a template to disallow moving or removing them. This is set via the block’s lock attribute in the template markup.

A real-world use case: a news site where the editorial team writes posts but should not modify the header or the sponsored content zone. Lock the header template part and the sponsor block group in your single.html template. Editors still have full access to the post content area but cannot touch the locked regions. Combine this with user role restrictions via the block editor filters for fine-grained editorial control without any custom plugin code.

Synced Template Parts for Global Content

WordPress 6.3 introduced synced patterns (previously called reusable blocks), but template parts offer a complementary approach for structural content. A template part updated in the Site Editor updates everywhere it is referenced instantly, without needing to publish individual posts. This is the right tool for: global call-to-action sections, sitewide notice banners, shared sidebar regions, and newsletter subscription forms that appear on multiple page types.

The key distinction between template parts and synced patterns: template parts are structural and live in the theme layer; synced patterns are content-oriented and live in the post layer. Use template parts when you want the block to appear as a named region in the Site Editor template view. Use synced patterns when you want to embed the same content block inside multiple posts or pages without it appearing as a top-level template region.

Exporting Templates for Version Control

The Site Editor’s Export function (Editor → Export) packages all database-stored template overrides back into theme files as a zip download. This workflow is essential for teams who prototype in the Site Editor but want to commit templates to a Git repository.

A recommended team workflow: keep a staging site where designers iterate using the Site Editor, export periodically, unzip the templates folder into the repository, review the diff, and deploy. This gives designers a visual editing environment while keeping developers in control of what goes into the codebase. Pair this with a staging-to-production deployment process that resets database template overrides on production, ensuring the file-based versions always take precedence after each deploy.

Performance Considerations

Template overrides have negligible performance impact on their own, WordPress resolves the hierarchy once per request and the resolved template is cached. The performance consideration lies in what you put inside your templates.

Each Query Loop block executes a separate database query. An archive template with one main Query Loop and one sidebar “related posts” Query Loop runs two queries per page load. That’s fine. An archive template with five Query Loop blocks, main listing, popular posts, recent posts, featured posts, and category highlights, runs five queries and can significantly impact page load times on high-traffic sites. If you need multiple queries, consider caching the results via transients through a custom dynamic block, or use a static Query Loop with generous caching at the server level.

Mastering template overrides is the final piece of the Full Site Editing puzzle. With archive templates, single templates, 404 pages, and search results all under your control, and template parts keeping your layouts DRY, you have everything needed to build fully custom block themes without a single line of PHP. This concludes the Full Site Editing Mastery series on Brndle.