Template files are modular, reusable files used to create web pages on your WordPress site. Some template files (such as the header and footer sections) are used on all pages of your site, while others are only used under specific conditions.

This article explains how WordPress decides which template file(s) to use to display individual pages. It will also help you decide which template file to edit if you want to customize an existing WordPress theme.

You can also use Conditional Tags to control which templates are loaded on a particular page.

Overview of the Template File Hierarchy

WordPress uses a query string to determine which page to display. The query string is the information found in the link to each section of your website.

Simply put, WordPress searches down the template hierarchy until it finds a matching template file. To decide which template file to use, WordPress does the following:

It matches each query string with a query type to determine which page is requested (e.g., a search page, a category page, etc.).
It selects the template in the order determined by the template hierarchy.
It searches the current theme’s directory for template files with specific names and uses the first matching template file specified in the hierarchy.

You can decide whether or not to implement a specific template file, except for the base index.php template file.

Note: The PHP file extension is used in these examples. Block themes use HTML files, but the template hierarchy is the same.

If WordPress cannot find a matching template file, it jumps to the next file in the hierarchy. If no matching template files are found, the theme’s index.php file is used.

Child Theme Cases:

If you are using a child theme, any files you add to your child theme will override the same file in the parent theme. For example, if both themes contain the same template (category.php), the child theme’s template will be used.

If a child theme has a more specific template (category-unicorns.php) and the parent theme has a lower priority template (category.php), then the child theme’s category-unicorns.php file will be used.

However, if the child theme only contains a general template (category.php) and the parent theme contains a specific one (category-unicorns.php), then the specific template (category-unicorns.php) from the parent theme will be used.

Examples: Category Page

If your blog is at http://example.com/blog/ and a visitor clicks on a category page like http://example.com/blog/category/your-cat/, WordPress searches the current theme’s directory for a template file matching the category ID to render the correct page:

category-{slug}.php: It first searches for a matching template file based on the category’s short name (slug). If the category name is “news”, it searches for category-news.php.
category-{id}.php: If category-news.php does not exist and the category ID is 4, it searches for a template file named category-4.php.
category.php: If category-4.php does not exist, it searches for category.php, which is a more general category template.
archive.php: If category.php also does not exist, it returns to archive.php, which is the general archive template.
index.php: If archive.php is also missing, it finally returns to index.php, which is the main theme template file. Detailed Template Hierarchy

While the template hierarchy is easier to understand as a diagram, the following sections explain the order in which WordPress calls template files for a range of query types: