Registers a new script.

Description

Registers a script to be enqueued later using the wp_enqueue_script() function.

See also

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

Parameters

$handlestringrequired

Name of the script. Should be unique.

$srcstring|falserequired

Full URL of the script, or path of the script relative to the WordPress root directory.
If source is set to false, script is an alias of other scripts it depends on.

$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'.

Default:array()

Return

More Information

Scripts that have been pre-registered using wp_register_script() do not need to be manually enqueued using wp_enqueue_script() if they are listed as a dependency of another script that is enqueued. WordPress will automatically include the registered script before it includes the enqueued script that lists the registered script’s handle as a dependency.

Usage

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

• Registering scripts is technically not necessary, but highly recommended nonetheless.
• If the handle of a registered script is listed in the $deps array of dependencies of another script that is enqueued with wp_enqueue_script(), that script will be automatically loaded prior to loading the enqueued script. This greatly simplifies the process of ensuring that a script has all the dependencies it needs. See below for a simple example.
• So, the main purpose of the register functions is to allow you to simplify your code by removing the need to duplicate code if you enqueue the same script or style in more than one section of code. The benefits of this are many and probably don’t need to be listed here.
• 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.

Notes

• The function should be called using the wp_enqueue_scripts or init action hook if you want to call it on the front-end of the site. 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 often lead to unexpected results and should be avoided.
• If attempt 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

Delayed Script Loading

WordPress provides support for specifying a script loading strategy via the wp_register_script() and wp_enqueue_script() functions, by way of the strategy key within the new $args array parameter introduced in WordPress 6.3.

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 registration:

wp_register_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.

Core-Registered Scripts

By default, WordPress bundles many popular scripts commonly used by web developers besides the scripts used by core itself. Below is an (incomplete) list of the handles and paths of these scripts.

Source

function wp_register_script( $handle, $src, $deps = array(), $ver = false, $args = array() ) {
	if ( ! is_array( $args ) ) {
		$args = array(
			'in_footer' => (bool) $args,
		);
	}
	_wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );

	$wp_scripts = wp_scripts();

	$registered = $wp_scripts->add( $handle, $src, $deps, $ver );
	if ( ! empty( $args['in_footer'] ) ) {
		$wp_scripts->add_data( $handle, 'group', 1 );
	}
	if ( ! empty( $args['strategy'] ) ) {
		$wp_scripts->add_data( $handle, 'strategy', $args['strategy'] );
	}
	return $registered;
}

View all references View on Trac View on GitHub

Changelog