Taking advantage of the template_include filter

If you are like me, you often want to control what template file WordPress uses. Some of the methods I’ve seen around the internet try to use template_redirect. Others are even worse and employ sticking tons of conditionals inside WordPress template files (eg category.php).

Well I am here to tell you there is a much easier way. It’s fairly unknown and sparsely documented. It’s the template_include filter.

The use cases for template_include are endless but I will give you a great example where I recently took advantage of it.

Let’s say you have a category structure like below:

  • Audio
  • News
    • Local
    • Health
    • Technology
    • Sports
    • Politics
    • Travel
  • Videos

Looks straight forward, right? Using the normal WordPress template hierarchy you can easily target these categories. We all know category-news.php would be used when viewing the News category or category-health.php would take care of the Health category.

However, what if you want to create a unique template for all the News sub-categories? Here are the two options you will usually find.

  1. Create a category.php file and use conditionals to target the individual sub categories. Lame!
  2. Create a template file for each sub-category (category-local.php, category-health.php, etc). Even more lame!

I want to have one template file that will be used for all the News sub-categories, not conditionals or duplicate scattered everywhere. With single snippet (which would be in functions.php) using the template_include filter this can be done!

add_filter( 'template_include', 'ja_template_check' );
function ja_template_check( $template ) {
if ( is_category() ){
// Get category information
$cat = get_query_var( 'cat' );
$category_info = get_category( $cat );
// News sub-categories, where 7 is the ID for News
if ( $category_info->parent == 7 ){
return get_stylesheet_directory() . '/subcategory-news.php';
return $template;
view raw gistfile1.php hosted with ❤ by GitHub

The code above first checks to see if you are looking at a category. If that is true it then checks to see if the parent category ID is 7. Finally, if this checks out it uses a template file I created,  subcategory-news.php.

Pretty easy, right?

Props to @wpmuguru for sending me in this direction.


  1. GaryJ says


    Slight re-working of your code which:
    * Adds DocBlock documentation, so people copying the snippet know what it does, and where it came from.
    * Returns early (good practice), if not a category.
    * Extracts the key bit of information (the cat ID, 7) to the top of the function, so people can easily find this value to edit.
    * Renamed a variable and the function, so it is more self-documenting.
    * Tidied up some redundant lines of code.

    In short, nothing wrong with the logic, just commenting on the presentation of your code 😉

  2. says

    Jared (and Gary),

    Thanks for this. I adapted it for a client site to force use of a separate “print” template. (Long story, but a simple print stylesheet wouldn’t do.)

    Anyway, in my experience with the code above, WordPress was looking for a local path, not a URI. I changed your get_stylesheet_directory_uri() to a get_stylesheet_directory() and it worked beautifully.

    Thanks again!

  3. says

    It’s worth noting that the filter now passes the $template variable as an argument, so there is no need to use:

    Instead you can start with:

    Nice article. I found this yesterday when looking for a way to pull a custom template within my plugin.

Leave A Reply