The Powerful WP_enqueue_script Function in WordPress

by

mcampagnini

on

February 10, 2019

How to Use the WordPress wp_enqueue_script Function

This powerful WordPress hook can link Javascript files into the head or footer in WordPress. By combining a custom plugin and wp_enqueue_script we can add Google Analytics, Fonts, Icon Kits, and more.

Function Definition

By enqueuing scripts or styles, WordPress will register the file and prevent it from being added multiple times. In addition, you can use the function to declare dependencies or identify the version. If the script has not been registered, it will be appended to the head or footer.

Extra Reading

Visit the links below for more information on wp_enqueue_script.

Read about this function on the WordPress.org code reference.

WordPress Theme Handbook shows how to add Javascript and CSS.

Read about wp_register_script() on the WordPress code reference.

wp_enqueue_script( string $handle, string $src = '', array $deps = array(), string|bool|null $ver = false, bool $in_footer = false )

WP_enqueue_script() and WP_register_script() in action

The following example demonstrates how to enqueue an external script into your WordPress page.



define('SBRP_PLUGIN_PATH', 	 plugins_url('', __FILE__));

function function_name() {

	wp_enqueue_script( 'handle_name', SBRP_PLUGIN_PATH . '/utility.js' );
    
    // A registered script is not appended until you call wp_enqueue_script on the handle
    wp_register_script( 'my_script', SBRP_PLUGIN_PATH . '/other_script.js' );

}

// Hook into wp_enqueue_scripts and call our function when executed
add_action( 'wp_enqueue_scripts', 'function_name' );

// If we are on the home page, link the registered script
if ( is_home() ) {

	wp_enqueue_script( 'my_script' );

}

Line 1

First, we define a constant with the path to our sample plugin.

Line 3-10, 12

Next, we have our function that is called when the hook is executed (line 12). Our enqueued script from line 5 is linked inside the head of our WordPress page. The registered script on line 8 is not linked until called.

Line 14-18

Finally, Registering the script to be linked allows us to add the script when we want. Our example tests if the user is on the home page and enqueues the script that has the handle my_script. This avoids loading unnecessary files and reduces load times.

Tips for using wp_enqueue_script()

Scripts should only be linked with the enqueue function or you may have unexpected results.
You may register a script at any time using wp_register_script() and enqueue it at a later point.

Dynamically created Javascript

Add Javascript from your PHP code with wp_add_inline_script(). The example below adds Javascript stored in the $script variable to handle_name.



function function_name() {

	wp_enqueue_script( 'handle_name', SBRP_PLUGIN_PATH . '/utility.js' );

}

add_action( 'wp_enqueue_scripts', 'function_name' );

$script = "jQuery(document).ready(function($) { 
				// my code 
			});";
wp_add_inline_script( 'handle_name', $script );

Parameters for wp_enqueue_script()

$handle (string)(Required)
A unique name identifying the script.

$src (string)(Optional) = ''
The source destination of the file to be enqueued as a URL or path relative to the WordPress root directory.

$deps (array)(Optional) = array()
An array of registered handle names that the enqueued file requires to run.

$ver (string|bool|null)(Optional) = false
The script version number to be added to the $src as a query string. If false, the WordPress version number is appended to the $src. If null, no version is applied.

$in_footer (bool)(Optional) = false
Insert the script at the end of the page or in the head of the page (default).

WP_enqueue_script in WordPress Conclusion

Nearly all of my projects require several scripts that do not need to be loaded on every page. These scripts might be DataTables.js, Charts.js, a Contact Form, or other library that has a very specific task. By conditionally loading these scripts on the pages that require them, I optimize my sites for speed and give users a better experience. You can enqueue CSS stylesheet by using the near identical wp_enqueue_style() function. In conclusion, if this article helped, leave a comment below!