The WordPress Template Hierarchy

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.

Continue Learning

Previous: WordPress Templates and Template Parts

Next: Query Loops and Dynamic Content