load_template() │ WP 1.5.0

Connects the specified file in PHP using require_once.

Used to ensure that the WordPress environment is already set up at the time of file inclusion. The function also sets global variables: $posts, $post, $wp_did_header, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID.

Used By: locate_template()
Hooks from the function

Returns

null. Returns nothing, but includes the file in PHP.

Usage

load_template( $_template_file, $require_once, $args );
$_template_file(string) (required)
Server path to the file to be included.
$require_once(boolean)

true - will include the file using require_once, false - using require.

If the file inclusion occurs inside a loop and this parameter is set to true, then the first element of the loop will display correctly, and subsequent elements will be output as copies of the first element.

Default: true

$args(array) (Since WP 5.5)
Additional parameters for the included file. Use the variable $args in the included file.
Default: []

Examples

#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' );
}

#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 7.1

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 ); // @phpstan-ignore variable.undefined (It's extracted from query vars.)
	}

	/**
	 * 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