A guide to the template hierarchy in WordPress
All modern WordPress themes consist of templates, style sheets, javascript, and images. Together, these files determine how your site will look to users. Templates with specific names affect certain areas of your website.
Generally, a WordPress theme should contain templates for displaying categories, dates, archives, individual posts, custom pages, etc. As a user, you can create your own templates using a child theme.
Visual WordPress Template Hierarchy (cheat sheet)
The visual cheat sheet below explains which template files are used to display different pages on a WordPress site.
Hierarchy for the home page
By default, WordPress displays the most recent posts on the home page of your site. You can also configure this in Settings → Readng in the WordPress admin.
front-page.php- If present in the theme, WordPress will use this template file regardless of the Reading settings.
home.php- Will be loaded if
front-page.phpdoes not exist and “Your Recent Posts” is set in the WordPress Reading Preferences. page.php- Will be used if
front-page.phpdoes not exist and the “display static page” checkbox is checked in the WordPress Reading settings. index.php- If
front-page.php,page.phpandhome.phpdo not exist, WordPress will fall back toindex.phpto render the home page.
Hierarchy for single post
single-{post-type}-{slug}.php- Use this template to change the display of a specific single post for any post type. For example, if the post type is “project” and the label of the post is “apple”, then WordPress will look for
single-project-apple.php. single-{post-type}.php- WordPress will check if a template exists to display that particular post type. For example, if the post type is “project”, WordPress will look for
single-project.php. single.php- General template for displaying all posts.
singular.php- This fallback template is for displaying all pages of a single type.
index.php- If WordPress doesn’t find any of the previous templates, it will use
index.phpto render the page.
Hierarchy for single page
{custom-page-template}.php- The assigned template for the page.
page-{slug}.php- If the page label is “contact-us”, WordPress will look for
page-contact-us.phpto render. page-{id}.php- If the page ID is 12, WordPress will look for a template file named
page-12.php. page.php- Template for displaying all static pages.
singular.php- This template is the default fallback for all single type pages.
index.php- If WordPress doesn’t find any of the previous templates, it will use
index.phpto render the page.
Hierarchy for categories
category-{slug}.php- This template is used to display a category archive page for a specific category. For example, if the category label is “projects”, WordPress will look for the
category-projects.phptemplate. category-{id}.php- WordPress then looks for a template with a category ID. For example, if the category id is 12, then WordPress will look for
category-12.php. category.php- This template is used by default to display all category pages in WordPress.
archive.php- This template is used by default to display any archived pages.
index.php- The default fallback template if none of the previous ones are found.
Hierarchy for tags
tag-{slug}.php- If the tag label is “horrors”, WordPress will look for
tag-horrors.php. tag-{id}.php- If the tag id is 12, WordPress will look for the
tag-12.phptemplate. tag.php- Default template for tag archives.
archive.php- Default template for any archive page.
index.php- The default fallback template if none of the previous ones are found.
Hierarchy for taxonomies
The categories and tags discussed above are the two taxonomies that WordPress has by default. Users can also create their own custom taxonomies.
taxonomy-{taxonomy}-{term}.php- If you have a taxonomy of “genre” and have a term of “thriller”, then WordPress will look for the template
taxonomy-genre-thriller.php. taxonomy-{taxonomy}.php- For all “genre” taxonomy terms, WordPress will look for the
taxonomy-genre.phpfile if it doesn’t find the previous one. taxonomy.php- The default template for displaying any custom taxonomy archives.
archive.php- The default fallback for all archived pages in WordPress.
index.php- The default fallback template in WordPress.
Hierarchy for custom post types archives
archive-{post_type}.php- If you have custom post types “review”, WordPress will look for
archive-review.phpto render. archive.php- The default template for displaying all archived pages in WordPress.
index.php- The default fallback template in WordPress.
Hierarchy for author archives
author-{nicename}.php- If the author’s nickname is “hulk”, WordPress will look for
author-hulk.php. author-{id}.php- If the user ID is 6, WordPress will look for
author-6.phpto render the page. author.php- The default template used to display author archive pages in WordPress.
archive.php- The default template for displaying all archived pages in WordPress.
index.php- The default fallback template in WordPress.
Hierarchy for post archives by date
WordPress also displays posts on archive pages based on the date for months and years. Here’s what the templates for these pages look like.
date.php- Default template for date-based archives.
archive.php- The default template used to display archived pages in WordPress.
index.php- The default fallback template in WordPress.
Hierarchy for search results
search.php- The default page for displaying search results in WordPress.
index.php- The default fallback template in WordPress.
Hierarchy for 404
The 404 error page is displayed when WordPress cannot find the requested content.
404.php- The default template for displaying a 404 error page in WordPress.
index.php- The default fallback template in WordPress.
Hierarchy for attachments
MIME_type.php- mime_type denotes the file type. For example,
image.php,video.php,application.php. attachment.php- The default template for displaying attachment pages.
single-attachment.php- To display a single attachment.
single.php- The default template for displaying elements of a single type.
index.php- The default fallback template in WordPress.
Hierarchy for embeds
Starting with WordPress 4.5, you can use templates to render embedded content in WordPress.
embed-{post-type}-{post_format}.php- WordPress will first look for the post type and post format template. For example, if you have a “review” with “video”, WordPress will look for the
embed-review-video.phpfile. embed-{post-type}.php- If the post type is “review”, WordPress will look for
embed-review.php. embed.php- The default fallback for all inserts.
Other theme files
These files are not used in the hierarchy, but are plugged inside most templates as part of them.
header.php- Contains the title of the WordPress site and is usually called at the beginning of all template files. It usually contains the logo and menu, as well as the technical information of the
<head>tag – meta tags, calls to css and js files, analytics, page title, etc. Connected using theget_header(). footer.php- Used to create the footer section of a WordPress theme and is called at the end of all template files.
footer.phpusually contains copyright information, JS file calls, widget areas, site navigation. It is connected using theget_footer()function. sidebar.php- Used to create a site sidebar and called in template files like
index.php,page.php,single.phpto display the sidebar panels. It usually contains widget areas. It is connected using theget_sidebar()function. searchform.php- Template for displaying a search form in WordPress. It is connected using the
get_search_form()function. It usually contains widget areas. It is connected using theget_sidebar()function. functions.php- A file that contains the functionality of a theme. As a rule, it is used only to connect logically divided files with site functions from the includes/ or inc/ folder. It connects automatically when the theme is loaded.