Filter Hook since 1.5.0

template_include

Filters the final template file path WordPress is about to load

Description

template_include is the very last stop in the template hierarchy — return an absolute path to a PHP file and WordPress loads exactly that, bypassing the rest of the hierarchy.

When it runs

At the very end of template-loader.php's template hierarchy resolution, right before include().

Signature

apply_filters( 'template_include', string $template );

Parameters

$template string — Absolute path to the resolved template file.

Examples

Basic

add_filter( 'template_include', function( $template ) {
    if ( is_singular( 'book' ) ) {
        $custom = plugin_dir_path( __FILE__ ) . 'templates/single-book.php';
        if ( file_exists( $custom ) ) {
            return $custom;
        }
    }
    return $template;
} );

Serve a template shipped with a plugin for a custom post type, if the theme doesn't provide one.

Common Use Cases

Ship custom templates from a plugin
Override a theme's template for a specific condition
Serve a completely custom page (landing pages, builders)

Common mistakes

Returning a template path that doesn't exist or isn't checked with file_exists() — causes a fatal include error

Related hooks

Fires after template_redirect

FAQ

template_include vs single_template — which should I use?

single_template (and its siblings like page_template) only affect one specific query type; template_include is the catch-all that runs regardless of query type.

Source: wp-includes/template-loader.php

Group wizard

One session: this hook, then each related_hooks entry. Walk it and tell us what to change.

template_include → template_redirect

functions.php — template_include

functions.php

<?php
/**
 * Practice: hook into template_include
 */
add_filter( 'template_include', function( $template ) {
	// Write your callback here. Always return the value.

	return $template;
} );

Group tour

template_include · Hook 1 of 2 · Step 1 of 6

Meet template_include

Filters the final template file path WordPress is about to load

template_include is the very last stop in the template hierarchy — return an absolute path to a PHP file and WordPress loads exactly that, bypassing the rest of the hierarchy.

type filterphase templatesince 1.5.0source wp-includes/template-loader.php

apply_filters( 'template_include', string $template );

add_filter( 'template_include', function( $template ) {
    if ( is_singular( 'book' ) ) {
        $custom = plugin_dir_path( __FILE__ ) . 'templates/single-book.php';
        if ( file_exists( $custom ) ) {
            return $custom;
        }
    }
    return $template;
} );

PHP template_include · Hook 1 of 2 · Step 1 of 6

Practice the template_include WordPress filter hook in our interactive sandbox — a VS Code-style editor with a step-by-step template_include tutorial, add_filter exercises, and instant feedback. No local WordPress install required.