What is the WordPress Template Hierarchy and How Does it Work?

If you are looking into theme development, you need to understand the WordPress template hierarchy. The CMS uses template files to render content on the front end. Hence, learning the fundamentals of WordPress hierarchy is essential for customizing themes or building one from scratch.

Although creating a WordPress theme is no rocket science, you must be aware of the basics. Apart from secure WP hosting, domain, theme, and plugins, you need to understand template hierarchy. In this article, we explain how the WP template hierarchy, page structure, and template files work, so you can start building and customizing themes like a professional. Let’s dive in!

What is the WordPress Template Hierarchy?

WordPress template hierarchy is the structure deciding which templates to use and in what order when displaying a webpage. In technical terms, it uses query strings to browse the hierarchy until it finds the first matching template. This hierarchy allows web developers to create custom page layouts for different types of content by prioritizing specific template files over their generic counterparts.

• Tutorials
• WordPress

A Comprehensive Guide to Becoming a WordPress Contributor

Rajdeep Roy

June 28, 2024

If WordPress cannot find a specific template file, it will move down the hierarchy until it locates the first usable file. Therefore, understanding and utilizing the template hierarchy allows for greater flexibility and control over the appearance and functionality of a WordPress site.

Static websites typically use static HTML and CSS for rendering their content on the front end. However, WordPress being a dynamic platform is based on the PHP programming language. Every WordPress website loads tons of PHP files, each specifying how different sections on the page will look.

Every Content Management System searches for the template files every time you load a web application. For example, when using the WordPress search feature, the CMS searches for two template files.

1. Search.php determines how your search pages will look
2. Index.php is the default template file that WordPress uses when it cannot identify the top option within a hierarchy.

What are WordPress Template Files?

Template files are a part of the WordPress architecture. The code lays the pathway for displaying content on posts, pages, and other areas on the website. Template hierarchy WordPress is part of every theme or layout that you use. Classic WordPress themes generally use PHP files developed using HTML and PHP codes. While modern block themes just use HTML files.

Most WordPress sites need several template files to display content. Here are the seven commonly used template files you must be familiar with.

1. Index.php
2. Header.php
3. Footer.php
4. Sidebar.php
5. Functions.php
6. Comments.php
7. Single.php

Blog posts generally use the single.php file as the default template for displaying content while the header, footer, and sidebar on individual pages use their respective .php files. The last three files are called template partials as they can be used to define other templates as well. More on that later.

Understanding How Template Hierarchy Works

A typical WordPress theme consists of multiple templates. Therefore, the platform must decipher which template to use when displaying content. This is why some template files must take precedence over others. And that is the essence of template hierarchy.

High-priority template files are the backup if WordPress fails to locate a user-specific hierarchy. WordPress will look for a selected template file when users request to see a webpage. If the CMS cannot find the correct template, it will use the hierarchy to locate the next most suitable template.

For example, if you try to load a webpage, say for the category shared hosting, this is what happens in the background.

• WordPress will search for a template file called “category-shared-hosting.php” within the installed theme’s directory.
• If it can’t locate the file, WordPress will begin searching for the category ID instead. For example, “category-2.php.”
• Failing to find either template file will prompt WordPress to search for a generic “category.php” file.
• The search doesn’t end there as next in line is the “archive.php” file.
• If all else fails, WordPress will use your theme’s “index.php” file as the default template.

Every WordPress website comprises multiple categories, each with its own template hierarchy for seamless navigation and quick access. A typical website can be segregated into seven template styles. Let’s walk you through each in a bit more detail.

Front Page

The front page or the homepage is the most important landing page for a website since this is where visitors will normally land. The front page hierarchy generally consists of three template files, namely front-page.php, home.php, and index.php. WordPress will use this hierarchy when a user requests to see your website’s homepage.

Single Posts

There are three primary template files for single posts like blogs and articles. These are single,php, singular.php, and index.php. However, since there may be provisions for custom post types on the website, WordPress searches for two other template files before starting with these. So, the template hierarchy looks like this.

1. Single-{post-type}-{slug}.php
2. Single-{post-type}.php
3. Single,php
4. Singular.php
5. Index.php

Single Pages

Every page in a WordPress website apart from the homepage falls under the single page category. The template hierarchy is similar to single posts except for the optional custom template file. Let’s take a look at the hierarchy.

1. (Custom template file)
2. Page-{slug}.php
3. Page-{id}.php
4. Page.php
5. Singular.php
6. Index.php

Category Pages

The template hierarchy for categories works similarly to the single-page hierarchy. For instance, instead of searching for the page slug followed by the page ID, WordPress will look for the category slug and ID before searching for category.php, archive.php, and index.php.

Custom Post Types

If you are using a WordPress custom post types plugin or your theme has the feature built-in, the CMS will search for the post type’s archive before returning to the theme’s default archive.php and index.php files. For example, when searching for the custom product post type, the template hierarchy will be:

1. Archive-{post_type}.php
2. Archive.php
3. Index.php

Search Results Pages

Most WordPress themes today have a built-in search function. This requires the search.php template for the search results page. If your site relies on the search functionality, ensure that your WordPress theme has a template for the search page. If you are new to web development and need help finding a good WordPress theme, you can learn how to choose a WordPress theme here.

404 Error Pages

When visitors mistype a URL or try to view a page that doesn’t exist, WordPress will return a 404 error page. The WordPress template hierarchy is pretty simple. The CMS will first search for the 404.php file followed by index.php. Most WordPress themes come with a default 404.php file. But if it doesn’t we highly recommend creating a custom error page template.

• Comparison
• WordPress

WordPress vs WooCommerce: Exploring the Key Differences

Rajdeep Roy

June 28, 2024

Conclusion

The WordPress template hierarchy explains how the CMS searches for files when loading a web page. Being familiar with the template hierarchy of your website can help you optimize search results and reduce page load times, improving user experience. Don’t get overwhelmed by the details. Instead, you can start slow and get used to the process with practice.