1. Home
  2. Docs
  3. WordPress Developer
  4. WordPress Theme Development
  5. Theme Structure – The Theme Template Hierarchy

Theme Structure – The Theme Template Hierarchy

WordPress Themes live in subdirectories of the WordPress themes directory (wp-content/themes/ by default) . The Theme’s subdirectory holds all of the Theme’s stylesheet files, template files, and optional functions file (functions.php), JavaScript files, and images.For example, a Theme named “wpseeds” would reside in the directory wp-content/themes/wpseeds/.

WordPress Themes typically consist of three main types of files, in addition to images and JavaScript files.

  1. Stylesheet  : style.css :visual design and layout of the website pages.
  2. Template files which control the way the site pages generate the information from your WordPress database to be displayed on the site. I.e  index.php, page.php and more
  3. Functions file (functions.php) as part of the WordPress Theme files.

The minimum number of files is two: index.php and style.css.You could build a theme with just these two files, but we wouldn’t recommend it. Separating out things like the header and footer and creating different template files for static pages, archive pages and single posts, for example, will make easier and maintaining code more efficient.

WordPress themes involve a bunch files. And understanding those files is the key to understanding WordPress development.These are PHP files that contain a mixture of HTML, Template Tags, and PHP code.

When someone visits a page on your website, WordPress loads a template based on the request.

If your blog is at https://wpseeds.org/blog/ and a visitor clicks on a link to a category page such as https://wpseeds.org/blog/category/your-cat/, WordPress looks for a template file in the current theme’s directory that matches the category’s ID to generate the correct page. More specifically, WordPress follows this procedure:

Theme Template Hierarchy

  1. Looks for a template file in the current theme’s directory that matches the category’s slug. If the category slug is “seo,” then WordPress looks for a template file named category-seos.php.
  2. If category-seo.php is missing and the category’s ID is 7, WordPress looks for a template file named category-7.php.
  3. If category-7.php is missing, WordPress will look for a generic category template file, category.php.
  4. If category.php does not exist, WordPress will look for a generic archive template, archive.php.
  5. If archive.php is also missing, WordPress will fall back to the main theme template file, index.php.

The Template Hierarchy In Detail

Front Page display

If front-page.php exists, it will override the home.php template.then index.php

Single Post


Single Page

The template file used to render a static page (page post-type). Note that unlike other post-types, page is special to WordPress and uses the following patch:

  1. custom template file – The page template assigned to the page. 
  2. page-{slug}.php – If the page slug is recent-news, WordPress will look to use page-recent-news.php.
  3. page-{id}.php – If the page ID is 6, WordPress will look to use page-6.php.
  4. page.php
  5. singular.php
  6. Index.php


Rendering category archive index pages uses the following path in WordPress:

  1. category-{slug}.php – If the category’s slug is news, WordPress will look for category-news.php.
  2. category-{id}.php – If the category’s ID is 6, WordPress will look forcategory-6.php.
  3. category.php
  4. archive.php
  5. Index.php


To display a tag archive index page, WordPress uses the following path:

  1. tag-{slug}.php – If the tag’s slug is sometag, WordPress will look for tag-sometag.php.
  2. tag-{id}.php – If the tag’s ID is 6, WordPress will look for tag-6.php.
  3. tag.php
  4. Archive.php

Custom Taxonomies

Custom taxonomies use a slightly different template file path:

  1. taxonomy-{taxonomy}-{term}.php – If the taxonomy is sometax, and taxonomy’s term is someterm, WordPress will look for taxonomy-sometax-someterm.php. In the case of post formats, the taxonomy is ‘post_format’ and the terms are ‘post-format-{format}. i.e. taxonomy-post_format-post-format-link.php for the link post format.
  2. taxonomy-{taxonomy}.php – If the taxonomy were sometax, WordPress would look for taxonomy-sometax.php.
  3. taxonomy.php
  4. archive.php
  5. Index.php

Custom Post Types 

Custom Post Types use the following path to render the appropriate archive index page.

  1. archive-{post_type}.php – If the post type is product, WordPress will look for archive-product.php.
  2. archive.php
  3. index.php

Author display 

Based on the above examples, rendering author archive index pages is fairly explanatory:

  1. author-{nicename}.php – If the author’s nice name is matt, WordPress will look for author-matt.php.
  2. author-{id}.php – If the author’s ID were 6, WordPress will look forauthor-6.php.
  3. author.php
  4. archive.php
  5. index.php

Search Result 

Search results follow the same pattern as other template types:

  1. search.php
  2. index.php

404 (Not Found) 

Likewise, 404 template files are called in this order:

  1. 404.php
  2. index.php


Rendering an attachment page (attachment post-type) requires following the follow path:

  1. MIME_type.php – it can be any MIME type (For example: image.php,video.php, application.php). For text/plain, the following path is used (in order):
    1. text_plain.php
    2. plain.php
    3. text.php
  2. attachment.php
  3. single-attachment.php
  4. single.php
  5. index.php


To add a sidebar to WordPress you need to add the following steps:

  • Register the sidebar using register_sidebar()
  • Use dynamic_sidebar() in sidebar.php to pull in your widgets
  • Use get_sidebar() to include the sidebar in the appropriate place
  • Use CSS to style your work
Was this article helpful to you? Yes No

How can we help?