wp_enqueue_script() │ WP 2.1.0

Correctly connects the script (JavaScript file) to the page.

Using this function to connect js files is important because it allows you to later combine JS files into one without unnecessary problems. Also, in some cases, you will avoid script conflicts when a dependent script is connected before the main one (the one it depends on).

The function adds the script only if it has not been added yet and other scripts it depends on are registered. Dependent scripts are added automatically.

If the script has already been registered using wp_register_script(), then to connect it in this function you only need to specify the script identifier (in the first parameter):

// jquery is registered in WP by default.
// Therefore, to connect it, one line is enough:
wp_enqueue_script('jquery');

If the script is not registered, it can be registered and connected at the same time:

 wp_enqueue_script( 'newscript', get_template_directory_uri() . '/js/custom_script.js');

Returns

null. Returns nothing.

Usage template

//add_action( 'admin_enqueue_scripts', 'my_enqueue_scripts' );
//add_action( 'login_enqueue_scripts', 'my_enqueue_scripts' );
//add_action( 'enqueue_block_assets', 'my_enqueue_scripts' );
//add_action( 'enqueue_block_editor_assets', 'my_enqueue_scripts' );
add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );
function my_scripts_method(){
	wp_enqueue_script( 'newscript', get_template_directory_uri() . '/js/custom_script.js');
}

Usage

wp_enqueue_script( $handle, $src, $deps, $ver, $in_footer );

$handle(string) (required)

The name of the script (working title). A string in lowercase.

If the string contains a question mark (?): scriptaculous?v=1.2, then the preceding part will be the name of the script, and everything after will be added to the URL as query parameters. This allows you to specify the version of the connected script.

$src(string)

The URL of the script file. For example: http://example.com/wp-content/themes/my-theme/my-theme-script.js.

This parameter is only necessary when the script is not registered and WordPress does not yet know about this script, see the function wp_register_script().

You should not hardcode the URL; it should be determined dynamically. For this, use URL retrieval functions:

• plugins_url() - for plugins
• get_template_directory_uri() - for themes.

Links to external scripts can be specified without indicating the protocol: //otherdomain.com/js/their-script.js.

Already registered scripts in WP are listed below in this article.

Default: ''

$deps(array)

An array of script names that this script depends on; scripts that must be loaded before this script. This parameter is only necessary if WordPress does not yet know about this script.
Default: array()

$ver(string)

A string indicating the version of the script, if it has one. This parameter is used to ensure that the client receives the correct version of the script, not from the cache.

If the parameter is not specified, the version of the script will be the version of WordPress.

If you specify null, no version will be added.

Default: false

$args(array)

Parameters for connecting the script. Two parameters are supported:

• in_footer(bool) - Default: false. Whether to output the script in the footer. By default, scripts are placed in the head section. If this parameter is true, the script will be output at the end of the body tag.

  If due to dependencies on other scripts it is not possible to connect the current script in the footer, then the value of this variable will be ignored and the script will be connected in the head.

  The function wp_footer() must be called in the theme before the closing </body> tag.

  Behaves the same as the previous (pre WP 6.3) implementation of the $in_footer parameter.

• strategy(string) - Default: ''. Indicates how (by what strategy) the script should be loaded. Two values are available: defer and async for deferred and asynchronous scripts, respectively.

  By default, blocking behavior is used, which maintains backward compatibility with WP versions below 6.3.

Before WP 6.3, this parameter was called $in_footer and accepted true/false.
Starting from version 6.3, the parameter began to accept an array of data, and the previous parameter $in_footer was moved to the array element in_footer:

[
	'in_footer' => true,
	'strategy'  => 'async',
]

Read more about this change here.

Default: []

Examples

// For frontend of the site
add_action( 'wp_enqueue_scripts', 'my_scripts_method' ); 

function my_scripts_method() {
	wp_enqueue_script( 'scriptaculous' );            
}

add_action( 'wp_enqueue_scripts', 'my_scripts_method', 11 );
function my_scripts_method() {
	wp_deregister_script( 'jquery' );
	wp_register_script( 'jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js' );
	wp_enqueue_script( 'jquery' );
}    

add_action( 'wp_enqueue_scripts', 'my_scripts_method' );
function my_scripts_method() {
	$script_url = plugins_url( '/js/newscript.js', __FILE__ );
	wp_enqueue_script('custom-script', $script_url, array('jquery') );
}

add_action( 'wp', 'add_my_script_where_it_necessery' );
function add_my_script_where_it_necessery(){
	if( is_single() )
		add_action( 'wp_enqueue_scripts', 'my_scripts_method' );
}
function my_scripts_method() {
	$script_url = plugins_url( '/js/newscript.js', __FILE__ );
	wp_enqueue_script( 'newscript', $script_url, ['scriptaculous'] );
}

add_action( 'wp_enqueue_scripts', 'my_scripts_method' );

function my_scripts_method() {

	wp_enqueue_script( 'custom-script',
		get_template_directory_uri() . '/js/custom_script.js',
		array( 'jquery' )
	);
}

add_action( 'admin_menu', 'my_plugin_admin_menu' );
function my_plugin_admin_menu() {
	// Register plugin page
	$page = add_submenu_page(
		'edit.php',                     
		__( 'My plugin', 'myPlugin' ),  
		__( 'My plugin', 'myPlugin' ),  
		'manage_options',               
		'my_plugin-options',            
		'my_plugin_manage_menu'         
	);

	// Connect to a needed hook using the plugin page identifier 
	add_action( 'load-' . $page, 'my_plugin_admin_scripts' );
}

// This function will be called only on the page of the plugin
function my_plugin_admin_scripts() {
	wp_enqueue_script( 'my-plugin-script', plugins_url('/script.js', __FILE__) );
}

function my_plugin_manage_menu() {
	// page code
}

add_action('wp_enqueue_scripts', 'my_scripts_method');
function my_scripts_method() {
	wp_enqueue_script( 'custom-script',
		get_template_directory_uri() . '/js/custom_script.js',
		[ 'jquery' ],
		filemtime( get_theme_file_path('js/custom_script.js') )
	);
}

// Removing all versions of all scripts (and styles):
add_filter( 'script_loader_src', '_remove_script_version' );
add_filter( 'style_loader_src', '_remove_script_version' );
function _remove_script_version( $src ){
	$parts = explode( '?', $src );
	return $parts[0];
}

add_filter( 'script_loader_src', 'hb_remove_wp_version_from_src' );
add_filter( 'style_loader_src', 'hb_remove_wp_version_from_src' );
function hb_remove_wp_version_from_src( $src ) {
	 global $wp_version;
	 parse_str( parse_url( $src, PHP_URL_QUERY ), $query );
	 if ( ! empty($query['ver']) && $query['ver'] === $wp_version ) {
		  $src = remove_query_arg('ver', $src);
	 }
	 return $src;
}

Add Your Own Example

Scripts that come bundled with WP

WordPress registers many popular scripts by default (out of the box), i.e., such a script exists by default in WP. To add such a script to a page, you need to use its identifier in wp_enqueue_script( $id ).

The list is obtained from the global variable $GLOBALS['wp_scripts']. Registered scripts may change depending on the page you are on. In the admin area, the list will be larger.

Changes

In version 3.5, WordPress changed its stance on minifying scripts and CSS styles. Previously, minified files had extensions: .js and .css respectively, while unminified ones had .dev.js and .dev.css. Now, minified files have the extension: .min.js and .min.css, while regular ones have .js and .css.