Enqueues a script.

Description

Registers the script if $src provided (does NOT overwrite), and enqueues it.

See also

• WP_Dependencies::add()
• WP_Dependencies::add_data()
• WP_Dependencies::enqueue()

Parameters

$handlestringrequired

Name of the script. Should be unique.

$srcstringrequired

Full URL of the script, or path of the script relative to the WordPress root directory.
Default empty.

$depsstring[]optional

An array of registered script handles this script depends on.

Default:array()

$verstring|bool|nulloptional

String specifying script version number, if it has one, which is added to the URL as a query string for cache busting purposes. If version is set to false, a version number is automatically added equal to current installed WordPress version.
If set to null, no version is added.

Default:false

$argsarray|booloptional

An array of additional script loading strategies.
Otherwise, it may be a boolean in which case it determines whether the script is printed in the footer. Default false.

• strategy string

  Optional. If provided, may be either 'defer' or 'async'.

• in_footer bool

  Optional. Whether to print the script in the footer. Default 'false'.

• fetchpriority string

  Optional. The fetch priority for the script. Default 'auto'.

Default:array()

More Information

Usage

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

Links a script file to the generated page at the right time according to the script dependencies, if the script has not been already included and if all the dependencies have been registered. You could either link a script with a handle previously registered using the wp_register_script() function, or provide this function with all the parameters necessary to link a script.

This is the recommended method of linking JavaScript to a WordPress generated page.

As of WordPress 6.3, the new $args parameter – that replaces/overloads the prior $in_footer parameter – can be used to specify a script loading strategy. See the sections to follow for more information.

Supported strategies are as follows:

• defer
  • Added by specifying an array key value pair of 'strategy' => 'defer' to the $args parameter.
  • Scripts marked for deferred execution — via the defer script attribute — are only executed once the DOM tree has fully loaded (but before the DOMContentLoaded and window load events). Deferred scripts are executed in the same order they were printed/added in the DOM, unlike asynchronous scripts.
• async
  • Added by specifying an array key value pair of 'strategy' => 'async' to the $args parameter.
  • Scripts marked for asynchronous execution — via the async script attribute — are executed as soon as they are loaded by the browser. Asynchronous scripts do not have a guaranteed execution order, as script B (although added to the DOM after script A) may execute first given that it may complete loading prior to script A. Such scripts may execute either before the DOM has been fully constructed or after the DOMContentLoaded event.

Following is an example of specifying a loading strategy during script enqueuing:

wp_enqueue_script(
'foo',
'/path/to/foo.js',
array(),
'1.0.0',
array(
'strategy'  => 'defer',
)
);

The same approach applies when using

.

When applying a loading strategy via either the wp_register_script() and wp_enqueue_script() functions, the scripts dependency tree is taken into consideration and the most eligible loading strategy is applied.

While the intended (delayed) strategy passed by the code author may not be the final one, it will never be a stricter one, thus maintaining the integrity of the dependency tree.

Notes

• The function should be called using the wp_enqueue_scripts action hook if you want to call it on the front-end of the site, like in the examples above. To call it on the administration screens, use the admin_enqueue_scripts action hook. For the login screen, use the login_enqueue_scripts action hook. Calling it outside of an action hook can lead to problems, see the ticket #11526 for details.
• If you try to register or enqueue an already registered handle with different parameters, the new parameters will be ignored. Instead, use wp_deregister_script() and register the script again with the new parameters.
• jQuery UI Effects is not included with the jquery-ui-core handle.
• This function relies on the use of wp_head() and wp_footer() by the active theme. This means that it may not work with a few very old themes that do not call these functions. This is useful to keep in mind when debugging ancient themes.
• Uses: WP_Scripts::add(), WP_Scripts::add_data() and WP_Scripts::enqueue().
• Uses global: (unknown type) $wp_scripts.

Default Scripts and JS Libraries Included and Registered by WordPress

By default, WordPress installation includes many popular javascript libraries and scripts commonly used by web developers besides the scripts used by WordPress itself. Some of them are listed in the table below.

For a detailed list of names that can be used in place of the $handle parameter, see wp_register_script().

The list is far from complete. For a complete list of registered files inspect $GLOBALS['wp_scripts'] in the admin UI. Registered scripts might change per requested page.

* The listed dependencies are not complete.

Source

function wp_enqueue_script( $handle, $src = '', $deps = array(), $ver = false, $args = array() ) {
	_wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );

	$wp_scripts = wp_scripts();

	if ( $src || ! empty( $args ) ) {
		$_handle = explode( '?', $handle );
		if ( ! is_array( $args ) ) {
			$args = array(
				'in_footer' => (bool) $args,
			);
		}

		if ( $src ) {
			$wp_scripts->add( $_handle[0], $src, $deps, $ver );
		}
		if ( ! empty( $args['in_footer'] ) ) {
			$wp_scripts->add_data( $_handle[0], 'group', 1 );
		}
		if ( ! empty( $args['strategy'] ) ) {
			$wp_scripts->add_data( $_handle[0], 'strategy', $args['strategy'] );
		}
		if ( ! empty( $args['fetchpriority'] ) ) {
			$wp_scripts->add_data( $_handle[0], 'fetchpriority', $args['fetchpriority'] );
		}
	}

	$wp_scripts->enqueue( $handle );
}

View all references View on Trac View on GitHub

Changelog