Table of contents18
A few years ago, I spent an entire afternoon fighting a WordPress page that refused to use the template I wanted. I had edited single.php carefully, refreshed the page, and… nothing changed. I edited it again. Cleared caches. Stared at the screen. It turned out the page I was looking at wasn’t using single.php at all — WordPress had quietly chosen page.php instead, and nobody had ever explained to me how that decision gets made. If you’ve ever wondered why your page is using page.php and not single.php, this is WordPress template hierarchy explained the way I wish someone had explained it to me that afternoon.
I’ve been building WordPress themes for over eight years, and I can tell you the secret upfront: the WordPress template hierarchy explained simply is just a decision tree. WordPress looks at what kind of page is being requested, checks for the most specific template file first, and falls back to more general ones until it finds a match. That’s the whole system. In this guide, you’ll learn how that decision tree works with real examples, which template files actually matter, how to create your own custom page template, and how to debug it when WordPress picks the “wrong” file. If theme files have ever felt like a mysterious black box, we’re opening it together today.
Quick worry-killer before we begin: you don’t need to memorize the entire hierarchy chart. Professional theme developers don’t — they remember the pattern (specific beats general, everything falls back to index.php) and look up the details when they need them. Understand the pattern and you’ve understood 90% of the system. The rest is reference material, not homework.
What You’ll Learn in This Guide
- The one simple idea behind the entire template hierarchy
- How WordPress decides which template to use, walked through step by step
- The front-page puzzle: front-page.php vs. home.php (finally clarified)
- Why your page uses page.php and not single.php (and when it uses neither)
- The category archive example: the fallback chain in action
- The only template files worth knowing by heart
- How to create your own custom page template in five minutes
- How to debug “wrong template” issues like a professional
Ready? Let’s get started.
WordPress Template Hierarchy Explained: The One Simple Idea
Forget the scary charts for a moment. The entire template hierarchy runs on one rule: WordPress always uses the most specific template file available, falling back to more general ones until it finds a match. That’s it. Everything else is just details about what “most specific” means for each type of page.
Think of it like getting dressed for weather. You check: do I own a heavy winter coat? No? Then a medium jacket. No? Then a sweater. You don’t stand there paralyzed — you work down the list until something fits. WordPress does exactly the same thing with template files. For a category page, it asks: “Do I have a template for this exact category? No? For any category? No? For any archive? No? Then I’ll use index.php, the all-purpose fallback.”
Here’s the detail that makes the whole system click: index.php is the only template file WordPress actually requires. Every theme must have it. Everything else — single.php, page.php, archive.php — is optional specialization. A theme with only index.php and style.css still works; every page just looks the same. The hierarchy exists so theme developers can add more specific files and WordPress will automatically prefer them. Once that lands, the “mystery” evaporates: WordPress isn’t guessing, it’s shopping from most specific to least specific.
Let’s watch it make a decision in real time.
How WordPress Decides: A Decision Walk-Through
Imagine a visitor clicks a link to your “News” category page. Behind the scenes, WordPress runs through a checklist — a decision tree — that looks like this:
Visitor requests the "News" category page.
WordPress asks, in order:
1. Is there a category-news.php? (template for THIS exact category)
→ No? Continue.
2. Is there a category-7.php? (template for category ID 7)
→ No? Continue.
3. Is there a category.php? (template for ANY category)
→ No? Continue.
4. Is there an archive.php? (template for ANY archive page)
→ No? Continue.
5. Use index.php. (the universal fallback — always exists)Read that again slowly, because this is the pattern for everything. Specific first, general later, index.php always last. The slug version (category-news.php) beats the ID version (category-7.php) because a human-readable name is more specific than a number — though in practice, most developers use the slug version and ignore the ID one. If any step finds a file, the search stops immediately and that file renders the page.
Two things worth noticing. First, WordPress doesn’t scan your theme folder hoping to get lucky — it builds this exact checklist from the type of page requested, then checks each filename in order. Second, this means you control the outcome by adding files. Want all “News” posts to have a special layout? Create category-news.php and WordPress will automatically prefer it. You never tell WordPress to use it; the hierarchy does it for you. That’s the real power of understanding this system.
Now let’s clear up the confusion that trips up nearly everyone: the front page.
The Front-Page Puzzle: front-page.php vs. home.php
Here’s a confession: this confused me for my first two years of theme work. WordPress has two different concepts that sound almost identical — the “front page” (your site’s homepage) and the “posts page” (where your blog posts list lives) — and two different template files for them. Here’s how it actually works.
Go to Settings, then Reading in your dashboard. That one setting controls everything. If “Your homepage displays” is set to “Your latest posts,” your homepage is a blog listing, and WordPress checks for templates in this order: front-page.php, then home.php, then index.php. If it’s set to “A static page,” you’ve chosen a specific page as your homepage — WordPress checks front-page.php first, then falls back through the normal page templates (which we’ll cover next).
So what are the two files for? front-page.php is for your site’s front door, whatever it shows. It wins whenever it exists, regardless of your Reading settings. home.php is specifically the blog posts index — the page listing your latest posts, whether that’s your homepage or a separate “Blog” page you assigned under Reading settings. If you ever wonder “why isn’t my home.php doing anything?” — check Settings, then Reading first. Nine times out of ten, the answer lives there.
Bonus Tip: this is also why some themes seem to “ignore” your homepage customizations. If the theme ships a front-page.php, it overrides everything else for the front door — your Reading settings, your page templates, all of it. Knowing the hierarchy turns that mystery into a thirty-second diagnosis.
Single Posts vs. Pages: Why Your Page Uses page.php, Not single.php
Remember my afternoon of frustration from the intro? Here’s what I didn’t know: in WordPress, “posts” and “pages” are different content types with different template chains. The names single.php and page.php sound interchangeable, but they serve completely different masters.
When someone opens a blog post, WordPress walks this chain: single-post.php (only for the “post” type), then single.php (any single item), then singular.php (any single post OR page), then index.php. When someone opens a page (like “About” or “Contact”), it walks a different chain: page-about.php (this exact page’s slug), then page-42.php (this page’s ID), then page.php (any page), then singular.php, then index.php.
Do you see why my edits to single.php did nothing? I was editing the blog-post chain while staring at a page — which lives on the page chain. Pages never use single.php. Posts never use page.php. They’re parallel tracks that only meet at singular.php and index.php. The moment this clicked for me, half of all “wrong template” mysteries I’d ever encountered were solved retroactively.
This also answers a question beginners ask constantly: “I edited the wrong file — how do I know which file my page is actually using?” Hold that thought. We’re building a debugging checklist for exactly that, a few sections from now. First, the files worth memorizing.
The Only Template Files Worth Knowing by Heart
You don’t need all forty-odd filenames memorized. In real theme work, these nine cover nearly every situation you’ll meet:
- index.php — the universal fallback. Required in every theme. When nothing more specific exists, this renders the page.
- front-page.php — your site’s front door. Wins for the homepage whenever it exists.
- home.php — the blog posts listing specifically. Only matters when your homepage shows latest posts or you’ve assigned a posts page.
- single.php — an individual blog post. The file most bloggers customize first.
- page.php — an individual static page (About, Contact, Services).
- singular.php — a shared fallback for any single post or page. Handy when you want posts and pages to share one layout.
- archive.php — any listing page: categories, tags, authors, dates. The parent of all archive views.
- search.php — search results. 404.php — the “page not found” screen. These two are small but every complete theme needs them.
Learn these nine and their order, and you can reason through any template question. Everything else — category-news.php, page-about.php, single-product.php — is just the same “specific beats general” pattern applied to a particular slug or content type.
Now for the most practical skill in this guide: making your own.
How to Create a Custom Page Template in Five Minutes
Say you want a “Landing Page” layout — no sidebar, no header menu, just a clean full-width page — and you want to apply it to any page you choose. Custom page templates do exactly this, and they take one file and about five minutes.
Step 1: Create the file
In your (child!) theme folder, create a new PHP file. Name it something clear like template-landing.php. The name doesn’t matter to WordPress — what matters is what’s inside the file.
Step 2: Add the template header
At the very top of the file, add this special comment. It’s the magic label WordPress looks for:
<?php
/*
Template Name: Landing Page
*/
?>Template Name is what you’ll see in the dashboard — “Landing Page” appears as a choice in the page editor. Everything below this header is ordinary template code: copy your theme’s page.php content under it as a starting point, then modify the layout however you like (remove the sidebar call, widen the content area, whatever the design needs).
Step 3: Assign it to a page
Edit any page in your dashboard. In the page settings sidebar, find the Template dropdown — your “Landing Page” is now listed there. Select it, update the page, and visit it. Your custom layout is live.
Here’s what’s happening behind the scenes, in hierarchy terms: when a page has a custom template assigned, WordPress checks that assigned template before anything else in the page chain — before page-about.php, before page.php, before everything. The assigned template is the most specific choice possible because you chose it deliberately for that page. That’s a beautiful detail: the hierarchy respects your explicit choice above all its automatic rules.
Note: since you’re creating a new theme file, this belongs in a child theme so updates don’t erase it. If you haven’t set one up, my walkthrough on creating a WordPress child theme covers it in ten minutes. And if this is your first time editing theme files directly, read how to customize WordPress without breaking it first — the safety habits there will serve you for every file you ever touch.
Debugging “Wrong Template” Issues Like a Professional
Sooner or later, WordPress will render a page with a template you didn’t expect. Instead of guessing, run this checklist in order. (Template confusion often starts with a messy setup — installing a WordPress theme the right way prevents half of these issues before they start.) It solves the problem nearly every time.
Check 1: Are you looking at the right content type?
The most common “wrong template” is actually the right template for the wrong assumption — like my single.php vs. page.php afternoon. Ask: is this a post or a page? A category archive or a tag archive? Match what you’re viewing to the correct chain (posts use single.php, pages use page.php), and half the mysteries vanish immediately.
Check 2: Is a more specific file overriding yours?
Remember: specific beats general. If you edited category.php but the theme also ships category-news.php, your category.php edits will never show on the News category — the more specific file wins silently. List the files in your theme folder and walk the chain from most specific to least. The first file that exists is the one rendering your page. This single habit resolves most template confusion.
Check 3: Is a page template assigned in the dashboard?
An assigned custom template beats every automatic rule. Edit the page, check the Template dropdown in the sidebar — if something other than “Default template” is selected, that’s your answer. I’ve seen developers debug theme files for an hour before discovering a client had assigned a template months ago.
Check 4: Are your Reading settings what you think?
For anything homepage-related, go to Settings, then Reading before touching any file. A static front page vs. latest posts changes which chain WordPress walks entirely. Also confirm which page is actually assigned as the homepage — it’s embarrassingly common to customize the wrong page.
Check 5: Ask WordPress directly which file it’s using
When all else fails, make WordPress tell you. Add this tiny snippet to your child theme’s functions.php — it prints the current template’s filename as an HTML comment at the bottom of every page:
// Show the active template filename in an HTML comment (for debugging only)
add_action( 'wp_footer', function() {
echo '<!-- Active template: ' . basename( get_page_template() ) . ' -->';
} );Then view your page, right-click, choose “View page source,” and search for “Active template.” You’ll see the exact filename WordPress chose — no more guessing. Remove the snippet when you’re done debugging; it’s a diagnostic tool, not a permanent feature. (And yes — this snippet belongs in a child theme, and you should know how to customize functions.php safely before adding it.)
Run these five checks in order and you’ll diagnose any template mystery in minutes instead of afternoons. The hierarchy stops being a black box the moment you can ask it what it’s doing.
WordPress Template Hierarchy Explained: Frequently Asked Questions
What happens if my theme is missing a template file WordPress asks for? Nothing bad — that’s the whole point of the fallback chain. WordPress simply moves to the next, more general filename. The only file that must exist is index.php. A theme with just index.php and style.css renders every page of your site; it just renders them all the same way.
Can I change the template hierarchy order? You can’t reorder the built-in chain, but you don’t need to — you control the outcome by adding more specific files, assigning custom page templates, or using the template_include filter in code for advanced cases. For 99% of customization needs, adding the right file is simpler and safer than fighting the system.
Why does my custom page template not appear in the dropdown? Three usual causes: the Template Name header comment is missing or misspelled (it must say exactly “Template Name:”), the file isn’t a valid PHP file (check for typos above the header), or you’re editing a post instead of a page (custom page templates only appear on pages). Fix the header first — that’s the culprit most often.
Do block themes (like Twenty Twenty-Four) use the template hierarchy? Yes, but with a twist. Block themes use HTML template files in a templates/ folder instead of PHP files, and the same most-specific-wins logic applies to them. The PHP hierarchy described here governs classic themes; block themes follow the parallel block-template hierarchy. The mental model — specific beats general — is identical in both worlds. My complete guide to the WordPress block editor explains the block side of modern theming.
Is it safe to edit template files directly in my theme? Only in a child theme — never in the parent theme, where updates will wipe your edits. Template edits are also one of the classic ways beginners break sites (a missing PHP bracket whitescreens everything), so the safe-customization habits in my guide to common theme mistakes that break sites are worth reading before you start.
Final Thoughts
That frustrating afternoon I spent fighting single.php taught me something I now consider foundational: WordPress never picks templates randomly. It walks a decision tree — most specific file first, general fallbacks after, index.php always waiting at the bottom. Once you see the pattern, you stop guessing which file controls a page. You check the chain, you find the file, you make your change. The black box becomes a checklist.
Here’s my honest line: you still won’t memorize every filename, and you don’t need to. I look things up constantly. What matters is the mental model — specific beats general — because it turns every future template question into a solvable puzzle instead of a mystery. Congratulations: you now read WordPress theme behavior the way theme developers do.
Which template mystery brought you here — a stubborn page, a confusing homepage, or a category that wouldn’t cooperate? Tell me in the comments. And if the debugging snippet revealed a surprising filename, share it — your discovery might be exactly what the next reader needs to see.
