The WordPress template hierarchy determines which PHP file is used to render each page on your site. When a visitor requests a URL, WordPress follows a specific order of template file checks, starting with the most specific and falling back to more general templates. Understanding this hierarchy is essential for theme development.
This guide breaks down the WordPress template hierarchy, showing exactly which templates are checked for each type of page.
The Home Page
The homepage template selection depends on your reading settings. If your homepage displays your latest posts, WordPress checks for front-page.php, then home.php, then index.php. If your homepage uses a static page, WordPress uses the selected page’s template or front-page.php.
Most themes create a front-page.php for the homepage and a home.php for the blog posts index page. If neither exists, index.php handles everything.
Single Posts
Single post templates follow a specific hierarchy. WordPress first checks for single-post-{slug}.php (e.g., single-post-hello-world.php). If that doesn’t exist, it checks single-post-{id}.php. Then single.php, then singular.php, and finally index.php.
For custom post types, WordPress checks single-{posttype}-{slug}.php, then single-{posttype}.php, then single.php, singular.php, and index.php. This allows you to create unique templates for each post type.
Pages
Pages follow a similar hierarchy to posts. WordPress checks for the page’s custom template (set in the Page Attributes meta box), then page-{slug}.php, page-{id}.php, page.php, singular.php, and index.php.
Custom page templates are created by adding a Template Name header comment to a PHP file in your theme directory. The template appears as an option in the Page Attributes meta box on page editing screens.
Archive Pages
Archive pages display lists of posts. WordPress checks for archive.php for all archives, then more specific templates: category-{slug}.php and category-{id}.php for category archives, tag-{slug}.php and tag-{id}.php for tag archives, author-{nicename}.php and author-{id}.php for author archives, date.php for date-based archives, and finally index.php if none of the above exist.
For custom taxonomy archives, WordPress checks taxonomy-{taxonomy}-{term}.php, then taxonomy-{taxonomy}.php, then archive.php, and index.php.
Search and 404
Search results use search.php if it exists, or index.php if it doesn’t. You can customize the search results template to show search suggestions, highlight matching terms, or provide filters for post types.
The 404 page uses 404.php if it exists, or index.php as a fallback. Every theme should include a 404.php template that provides useful navigation options — search form, recent posts, category list — to help lost visitors find what they’re looking for.
Block Theme Templates
Block themes use a different template system. Templates are HTML files in the /templates directory with block markup instead of PHP. The hierarchy works similarly: WordPress checks for the most specific template first, falling back to more general ones. Block themes have replaced the PHP template hierarchy with a block-based equivalent that’s still in development.
The Bottom Line
The WordPress template hierarchy is logical and extensible. Specific templates override general ones. Start with index.php as your catch-all, then add more specific templates as needed. The hierarchy lets you create precise designs for different content types while maintaining a consistent fallback for anything you haven’t explicitly templated.