Template Hierarchy

The WordPress themeing system tries to match a theme file to a specific request. If a specific template file does not exist, the theme falls-back to the next available file (like maybe from the parent theme), and if that is not found, the last fall-back for all template files, the index.php file is used. In WordPress this fall-back method is called the Template Hierarchy.

For instance, if a theme provides a template file called category.php and a category page is being requested, the category.php file will be loaded. If the category.php file is not found, index.php is used as usual.

More Resources

Here are some diagrams meant to illustrate the file override paths of the Template Hierarchy:



Template Files

Template files are PHP files used to render web pages for a WordPress theme.

  • Template files can contain a mixture of HTML, WP Template Tags, and PHP code.
  • Template files can include other template files using WP Template Tags.
    When a piece of a page is included into a template file, such as including the header.php file, the include is called a Template Partial. Template Partials can be embedded in multiple template files, simplifying theme creation.

Here is a list of some basic theme templates and files recognized by WordPress:

Filename Description
index.php The main template file. It is required in all themes.
style.css The main stylesheet. It is required in all themes and contains the information header for your theme.
rtl.css The right-to-left stylesheet is included automatically if the website language’s text direction is right-to-left.
comments.php The comments template.
front-page.php The front page template is always used as the site front page if it exists, regardless of what settings on Admin > Settings > Reading.
home.php The home page template is the front page by default. If you do not set WordPress to use a static front page, this template is used to show latest posts.
header.php The header template file usually contains your site’s document type, meta information, links to stylesheets and scripts, and other data.
singular.php The singular template is used for posts when single.php is not found, or for pages when page.php are not found. If singular.php is not found, index.php is used.
single.php The single post template is used when a visitor requests a single post.
single-{post-type}.php The single post template used when a visitor requests a single post from a custom post type. For example, |single-book.php would be used for displaying single posts from a custom post type named book. The index.php is used if a specific |query template for the custom post type is not present.
archive-{post-type}.php The archive post type template is used when visitors request a custom post type archive. For example, |archive-books.php would be used for displaying an archive of posts from the custom post type named books. The archive.php template file is used if the archive-{post-type}.php is not present.
page.php The page template is used when visitors request individual pages, which are a built-in template.
page-{slug}.php The page slug template is used when visitors request a specific page, for example one with the “about” slug (page-about.php).
category.php The category template is used when visitors request posts by category.
tag.php The tag template is used when visitors request posts by tag.
taxonomy.php The taxonomy term template is used when a visitor requests a term in a custom taxonomy.
author.php The author page template is used whenever a visitor loads an author page.
date.php The date/time template is used when posts are requested by date or time.
archive.php The archive template is used when visitors request posts by category, author, or date. Note: this template will be overridden if more specific templates are present like category.php, author.php, and date.php.
search.php The search results template is used to display a visitor’s search results.
attachment.php The attachment template is used when viewing a single attachment like an image, pdf, or other media file.
image.php The image attachment template is a more specific version of attachment.php and is used when viewing a single image attachment. If not present, WordPress will use attachment.php instead.
404.php The 404 template is used when WordPress cannot find a post, page, or other content that matches the visitor’s request.

Template Tags

Template tags are used within themes to include other template files (template partials) and retrieve content from your database. The content could be anything from a blog title to a complete sidebar. Template tags are the preferred method to pull content into your theme files.

WP function File included Default include if file not found
get_header() header-{name}.php wp-includes/theme-compat/header.php
get_footer() footer-{name}.php wp-includes/theme-compat/footer.php
get_sidebar() sidebar-{name}.php wp-includes/theme-compat/sidebar.php
get_search_form() searchform.php WP auto-generated
comments_template() comments.php wp-includes/theme-compat/comments.php
get_template_part() {name}.php Returns nothing

Conditional Tags

WP function Ruturns true if:
is_404() The request returns an “HTTP 404: Not Found” error.
is_admin() The request is for the admin Dashboard or the administration panel.
is_archive() The request is for any type of archive page. An archive can be a Category, Tag, Author, Date, Custom Post Type or Custom Taxonomy based pages.
is_attachment() The request is for an attachment. An attachment is an image or other file uploaded through the post editor’s upload utility. Attachments can be displayed on their own ‘page’ or template.
is_author() The request is for an author archive page.
is_category() The request is for an existing category archive page.
is_home() The request is for the blog homepage.
is_network_admin() The request is for a network admin screen (wp-admin/network).
is_page() The request is for an existing single page.
is_post_type_archive() The request is for an archive page of a given post type(s).
is_search() The request is for the search result page.
is_single() The request is for an existing single post. Works for any post type, except attachments and pages
is_sticky() The current post is a Sticky Post meaning the “Stick this post to the front page” check box has been checked for the post.
is_tag() The request is for a Tag archive page.
is_tax() The request is for a custom taxonomy archive page.

When you use is_home() and is_front_page(), you have to use them in the right order to avoid bugs and to test every user configuration:

if ( is_front_page() && is_home() ) {
    // Default homepage
} elseif ( is_front_page() ) {
    // static homepage
} elseif ( is_home() ) {
    // blog page
} else {
    //everything else

Post Tags

WP function Use
the_content() Displays the post content HTML.
get_the_content() Returns the raw post content.
An important difference from the_content() is that get_the_content() does not pass the content through the ‘the_content’ filter. This means that get_the_content() will not auto-embed videos or expand shortcodes, among other things.