Skip to content
Reference

WordPress Block Theme Template Hierarchy

The full block-theme (FSE) template hierarchy: for every request type, the ordered list of templates WordPress looks for, most specific first, falling back to index.html. The block-era equivalent of the classic hierarchy chart.

For each request, WordPress looks for these templates in order — most specific first — and stops at the first one that exists in your theme’s /templates folder. The chain always ends at index.html.

Front page

The site's front page, whether it is set to your latest posts or a static page.

  1. front-page.html
  2. home.html
  3. index.html

front-page.html wins regardless of the Settings → Reading choice. If the front page is a static page and there is no front-page.html, it falls through to the static-page chain, not home.html.

Blog posts index

The page that lists your latest posts (the "posts page" in Settings → Reading).

  1. home.html
  2. index.html

Single post

An individual blog post.

  1. single-post-{slug}.html
  2. single-post.html
  3. single.html
  4. singular.html
  5. index.html

Single custom post type

An individual entry of a custom post type (e.g. a "book").

  1. single-{post-type}-{slug}.html
  2. single-{post-type}.html
  3. single.html
  4. singular.html
  5. index.html

For a post type "book" with slug "dune": single-book-dune.html, then single-book.html, then single.html.

Static page

A regular WordPress page.

  1. page-{slug}.html
  2. page-{id}.html
  3. page.html
  4. singular.html
  5. index.html

Page with a custom template

A page assigned a custom template in the editor's Template panel.

  1. {custom-template}.html
  2. page-{slug}.html
  3. page-{id}.html
  4. page.html
  5. singular.html
  6. index.html

Custom templates are declared in theme.json's customTemplates array and live in /templates. The assigned one wins over the whole page chain.

Category archive

The archive listing posts in one category.

  1. category-{slug}.html
  2. category-{id}.html
  3. category.html
  4. archive.html
  5. index.html

Tag archive

The archive listing posts with one tag.

  1. tag-{slug}.html
  2. tag-{id}.html
  3. tag.html
  4. archive.html
  5. index.html

Custom taxonomy archive

The archive for a term in a custom taxonomy.

  1. taxonomy-{taxonomy}-{term}.html
  2. taxonomy-{taxonomy}.html
  3. taxonomy.html
  4. archive.html
  5. index.html

Author archive

The archive of one author's posts.

  1. author-{nicename}.html
  2. author-{id}.html
  3. author.html
  4. archive.html
  5. index.html

Date archive

A year / month / day archive.

  1. date.html
  2. archive.html
  3. index.html

Post type archive

The archive index for a custom post type that has has_archive set.

  1. archive-{post-type}.html
  2. archive.html
  3. index.html

Search results

The results page for a site search.

  1. search.html
  2. index.html

404 (not found)

Shown when no content matches the URL.

  1. 404.html
  2. index.html

Attachment page

The page for a single media attachment.

  1. attachment.html
  2. single.html
  3. singular.html
  4. index.html

Many sites disable attachment pages entirely (they are thin content). If you keep them, this is the chain.

Privacy policy page

The page set as the site's privacy policy in Settings.

  1. page-privacy-policy.html
  2. privacy-policy.html
  3. page.html
  4. singular.html
  5. index.html

How this differs from the classic (PHP) hierarchy

  • Templates are .html files in /templates, not .php files in the theme root. There is no single.php — it is single.html.
  • Reusable regions (header, footer) are template PARTS in /parts, referenced with the wp:template-part block, not get_header() / get_footer() PHP calls.
  • There is no get_template_part() chain and no get_header()/get_footer(). Composition is done with the Template Part block inside the .html files.
  • index.html is REQUIRED. A block theme without templates/index.html is not a valid block theme — it is the mandatory final fallback for every route above.
  • The theme is declared a block theme by the PRESENCE of templates/index.html plus a theme.json, not by any header flag.
  • You can edit any of these templates in the Site Editor (Appearance → Editor) and save the changes to the database — which then OVERRIDE the theme's files until you clear the customization. This surprises people debugging "why does my template change do nothing".