load_template() │ WP 1.5.0

Require the template file with WordPress environment.

The globals are set up for the template file to ensure that the WordPress environment is available from within the function. The query variables are also available.

Used By: locate_template()
Hooks from the function

Return

null. Nothing (null).

Usage

load_template( $_template_file, $load_once, $args );
$_template_file(string) (required)
Path to template file.
$load_once(true|false)
Whether to require_once or require.
Default: true
$args(array)
Additional arguments passed to the template.
Default: empty array

Examples

0

#1 Including a template file in the plugin, with the ability to change it in the theme

Suppose we create a plugin and in it we need to specify the template file that will be used in the theme. Consequently, the template file will be different for different themes and we need to leave the possibility to change the template file in the theme. To do this, we will connect the plugin file, only if it is not defined in the theme:

// return file path if the child or parent theme has such a file
$overridden_template = locate_template( 'some-template.php' );

if ( $overridden_template ) {

	load_template( $overridden_template );
}
// file is not found in the theme or child-theme
else {
	// load the file from the 'templates' directory of the plugin
	load_template( __DIR__ . '/templates/some-template.php' );
}
0

#2 Send variable (data) to the template file

You can send additional variable with load_template() by passing the third parameter.

$args = [
	'text' => 'Hello Template File',
];

$template = locate_template( 'template.php' );

if( $template ){

	load_template( $template, true, $args );
}

In template.php file you can access this variable like this:

echo $args['text']; //> "Hello Template File"

Notes

  • Global. Array. $posts
  • Global. WP_Post. $post Global post object.
  • Global. true|false. $wp_did_header
  • Global. WP_Query. $wp_query WordPress Query object.
  • Global. WP_Rewrite. $wp_rewrite WordPress rewrite component.
  • Global. wpdb. $wpdb WordPress database abstraction object.
  • Global. String. $wp_version
  • Global. WP. $wp Current WordPress environment instance.
  • Global. Int. $id
  • Global. WP_Comment. $comment Global comment object.
  • Global. Int. $user_ID

Changelog

Since 1.5.0 Introduced.
Since 5.5.0 The $args parameter was added.

load_template() code WP 6.8

wp-includes/template.php 
function load_template( $_template_file, $load_once = true, $args = array() ) {
	global $posts, $post, $wp_did_header, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID;

	if ( is_array( $wp_query->query_vars ) ) {
		/*
		 * This use of extract() cannot be removed. There are many possible ways that
		 * templates could depend on variables that it creates existing, and no way to
		 * detect and deprecate it.
		 *
		 * Passing the EXTR_SKIP flag is the safest option, ensuring globals and
		 * function variables cannot be overwritten.
		 */
		// phpcs:ignore WordPress.PHP.DontExtract.extract_extract
		extract( $wp_query->query_vars, EXTR_SKIP );
	}

	if ( isset( $s ) ) {
		$s = esc_attr( $s );
	}

	/**
	 * Fires before a template file is loaded.
	 *
	 * @since 6.1.0
	 *
	 * @param string $_template_file The full path to the template file.
	 * @param bool   $load_once      Whether to require_once or require.
	 * @param array  $args           Additional arguments passed to the template.
	 */
	do_action( 'wp_before_load_template', $_template_file, $load_once, $args );

	if ( $load_once ) {
		require_once $_template_file;
	} else {
		require $_template_file;
	}

	/**
	 * Fires after a template file is loaded.
	 *
	 * @since 6.1.0
	 *
	 * @param string $_template_file The full path to the template file.
	 * @param bool   $load_once      Whether to require_once or require.
	 * @param array  $args           Additional arguments passed to the template.
	 */
	do_action( 'wp_after_load_template', $_template_file, $load_once, $args );
}

Theme files connection