← Back to Blog

The WordPress Template Hierarchy

The WordPress template hierarchy is the ordered set of templates WordPress checks when deciding how to display a request.

Veyra Admin

5 min read

  • Guide
  • Intermediate
  • 5 minutes read
  • Reviewed August 5, 2026
  • WordPress themes and templates

The WordPress template hierarchy is the ordered set of templates WordPress checks when deciding how to display a request.

It allows a theme to provide a general fallback and add more specific layouts only where needed.

How Template Selection Works

WordPress first determines the type of request: a single post, page, category archive, custom taxonomy, search result, 404 response or another query context.

It then checks for templates from most specific to more general. The first available match is used.

If no specialized template exists, WordPress continues through the hierarchy until it reaches the theme's final fallback.

Single Content Examples

For a classic theme displaying an individual post, WordPress may consider templates such as:

  • A custom template assigned to the post.
  • single-post-{slug}.php where supported by the hierarchy.
  • single-{post_type}.php.
  • single.php.
  • singular.php.
  • index.php.

Block themes use corresponding HTML template slugs and the same underlying query context, although exact files and editable template entities differ.

Pages and Front Pages

Pages have several special cases.

A page can use an assigned custom template. WordPress can also look for templates based on the page slug or ID before falling back to page.php, singular.php and index.php in classic themes.

The site's front page can use front-page behavior, while the posts index can use home. These are different concepts even when one page appears to serve both roles in a simple configuration.

Archive Hierarchies

Archive requests include:

  • Post type archives.
  • Category archives.
  • Tag archives.
  • Custom taxonomy terms.
  • Author archives.
  • Date archives.

A custom post type archive can use a type-specific template before falling back to a general archive template. A taxonomy term can use templates specific to the taxonomy or term before reaching broader archive and index fallbacks.

Custom Post Types

A custom post type named event can have dedicated single and archive templates.

This keeps the content model independent from the blog while still using the theme's shared header, footer, styles and fallback system.

The post type must be registered with the relevant public and archive behavior for those URLs to exist.

Why Fallbacks Matter

A theme does not need a separate file for every possible request.

A good fallback structure reduces duplication and ensures newly registered content still renders. Specialized templates should exist when the design or information architecture genuinely differs.

Without suitable fallbacks, a custom content type can appear broken even though WordPress successfully loaded a generic template.

Child Themes and the Hierarchy

Child themes can override parent-theme templates.

When both themes contain a matching template, the child version is generally used. A more specific template in the child theme can also take priority over a less specific parent template.

This makes child themes useful for targeted presentation changes, but overrides must be reviewed when the parent theme evolves.

Debugging Template Selection

When the wrong layout appears:

  1. Confirm the request type and queried object.
  2. Check the active theme and child theme.
  3. Review available template names.
  4. Check for Site Editor customizations stored in the database.
  5. Clear caches.
  6. Inspect plugins that filter template selection.
  7. Verify rewrite rules and public query settings.

Frequently Asked Questions

Does WordPress choose templates by URL alone?

No. It uses the resolved query context, which is influenced by rewrite rules, registered content types and query variables.

Must every theme include all hierarchy templates?

No. A theme can rely on general fallbacks and add specific templates as needed.

Is the hierarchy only for classic themes?

No. Block themes use the same conceptual request hierarchy with block-based templates.

Applying The WordPress Template Hierarchy in a Real WordPress Project

Separate content, presentation and permanent functionality. Test the editing workflow as well as the public output, because a theme decision affects templates, design controls, accessibility, performance and future redesign work.

A connected concept is Template Hierarchy for Custom Content. Reading the two together helps separate the immediate task from the wider WordPress responsibility.

A useful implementation begins by writing down the current state, the intended outcome and the evidence that will prove the change worked. This prevents a configuration screen, plugin recommendation or code snippet from becoming the entire strategy.

A Practical Example

Imagine a team making this decision for a production WordPress site. The useful question is not only “Can WordPress do this?” but “Which layer owns it, who maintains it, what data does it affect and how will we verify it after an update?”

Write the answer in operational terms. Name the content, user, setting, file, API or service involved. Then identify what should remain true if the theme changes, a plugin is replaced or the site is migrated.

Questions to Ask

  • What user or system problem does this solve?
  • Which WordPress layer owns the behaviour?
  • What data is created or changed?
  • Who may perform the action?
  • What can fail, and how will that failure be visible?
  • How is the result tested after updates?
  • What is the migration or removal path?

Official Reference Context

The Theme Handbook is the primary version-specific reference for this topic. Use the current documentation to verify interface labels, supported APIs and behaviour before applying instructions to a production site.

How to Verify the Result

  • Test representative templates on mobile and desktop.
  • Check keyboard navigation, headings, contrast and focus.
  • Switch editing contexts and confirm that the team knows where each design decision is stored.

Sources and Further Reading

Continue Learning