WordPress Template Hierarchy Example: Choose the Right Theme File

Last reviewed: April 23, 2026

Most theme bugs start with the wrong assumption about which template file WordPress is loading. Developers edit single.php while the active request is using single-product.php, or they change front-page.php expecting it to affect the posts index.

This guide explains the WordPress template hierarchy with practical examples for classic and block themes, then shows a safe debugging workflow you can use before editing production theme files.

The mental model

WordPress looks at the current query, determines the request type, and searches for templates from most specific to most general. If no specific file exists, it falls back until it reaches index.php in a classic theme or index.html in a block theme.

Common template paths

Request	Common classic theme files	What to check first
Single blog post	single-post.php, single.php, singular.php, index.php	Post type and assigned custom template
Page	page-{slug}.php, page.php, singular.php, index.php	Page slug, page ID, and page template
Category archive	category-{slug}.php, category.php, archive.php, index.php	Term slug and taxonomy
Custom post type archive	archive-{post_type}.php, archive.php, index.php	Whether has_archive is enabled
Posts index	home.php, index.php	Settings > Reading

Add a temporary template logger

When debugging production-like behavior, log the selected template rather than guessing. Use this only in a development environment or behind an administrator check.

<?php
add_filter( 'template_include', 'vulnwp_log_selected_template', 99 );

function vulnwp_log_selected_template( $template ) {
	if ( ! current_user_can( 'edit_theme_options' ) ) {
		return $template;
	}

	error_log(
		sprintf(
			'Template selected: %s | Request URI: %s',
			$template,
			isset( $_SERVER['REQUEST_URI'] ) ? sanitize_text_field( wp_unslash( $_SERVER['REQUEST_URI'] ) ) : ''
		)
	);

	return $template;
}

The filter returns the original template unchanged. It only records what WordPress already selected.

Choose the least invasive file

If only one category archive needs a different layout, create category-security.php rather than changing archive.php. If all archives need a shared layout, edit archive.php and keep taxonomy-specific files for exceptions.

themes/your-theme/
  category-security.php
  category.php
  archive.php
  index.php

This order keeps changes predictable. The most specific file wins, and the general files stay reusable.

Block theme note

Block themes use HTML templates, usually in the /templates directory, but the hierarchy is conceptually the same. A single post can resolve through a specific single template, a general singular template, and finally the index template.

Production workflow before editing

1. Identify the request type. Confirm whether you are looking at a page, post, archive, search result, front page, or posts index.
2. Check assigned templates. Pages and some custom post types can have manually selected templates.
3. Check child theme overrides. A child theme file can override a parent theme file.
4. Confirm the selected file. Use a local logger, Query Monitor, or theme debugging tools.
5. Edit the narrowest correct template. Avoid global template changes for local layout problems.

Common mistakes

• Confusing front-page.php and home.php. The front page and blog posts index are different concepts.
• Editing parent themes directly. Updates can overwrite those changes.
• Changing index.php first. It is the fallback, not the best place for every layout fix.
• Ignoring custom post type archive settings. No archive template will help if the archive is not enabled.
• Duplicating whole files unnecessarily. Prefer template parts for shared markup.

Related reading

Template choice often pairs with query behavior. Read the pre_get_posts example before changing archive queries, and the custom post type example before creating CPT templates.

References and further reading

• WordPress Theme Handbook: Template Hierarchy
• WordPress Theme Handbook: Templates
• WordPress Code Reference: template_include