wppaste
WordPress

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

Since
2.1.0, 6.3.0, 6.9.0, 7.0.0
Source
wp-includes/functions.wp-scripts.php:473

Load a JavaScript file on a WordPress page with wp_enqueue_script(), declaring its handle, source URL, dependencies, version, and loading strategy. Call it from a wp_enqueue_scripts or admin_enqueue_scripts callback. Since 6.3 the $args array accepts 'strategy' ('defer' or 'async') and 'in_footer'; newer releases add 'fetchpriority' and script module dependencies.

Enqueues a script.

Description

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

Compatibility

WordPress
since 7.0.0
PHP
7.4–8.6-dev
  • 6.7.7
  • 6.8.8
  • 6.9.7
  • 7.0.4
  • 7.1.0

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$handlestring
Name of the script. Should be unique.
$srcstringoptional
Full URL of the script, or path of the script relative to the WordPress root directory.
Default empty.Default: ''
$depsstring[]optional
An array of registered script handles this script depends on. Default empty array.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 extra args for the script. Default empty array. Otherwise, it may be a boolean in which case it determines whether the script is printed in the footer. Default false.Default: array()

  • $strategystring

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

  • $in_footerbooldefault: 'false'

    Optional. Whether to print the script in the footer.

  • $fetchprioritystringdefault: 'auto'

    Optional. The fetch priority for the script.

  • $module_dependenciesarray

    Optional. IDs for module dependencies loaded via dynamic import. Default empty array. For the full data format, see the $deps param of wp_register_script_module(). When provided, the script must either be printed in the footer (with in_footer set to true) or use a deferred loading strategy (defer), so that the script modules import map is printed before the script is evaluated. Otherwise dynamic imports may fail to resolve.

Code examples

Every example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.

Enqueue a deferred front-end script

Register and enqueue a plugin script with a dependency, a cache-busting version, and the defer strategy from a wp_enqueue_scripts callback.

add_action( 'wp_enqueue_scripts', 'myplugin_enqueue_assets' );

function myplugin_enqueue_assets() {
	wp_enqueue_script(
		'myplugin-app',
		plugins_url( 'js/app.js', __FILE__ ),
		array( 'wp-api-fetch' ),
		'1.4.2',
		array(
			'strategy'  => 'defer',
			'in_footer' => true,
		)
	);
}

The registration step never overwrites an existing handle, so if another plugin registered 'myplugin-app' first, your $src is silently ignored; pick a prefixed, unique handle.

Pass server data to an enqueued script

Attach a small inline configuration object before the script runs instead of printing globals in the template.

add_action( 'wp_enqueue_scripts', 'myplugin_enqueue_map' );

function myplugin_enqueue_map() {
	wp_enqueue_script(
		'myplugin-map',
		plugins_url( 'js/map.js', __FILE__ ),
		array(),
		'2.0.0',
		array( 'in_footer' => true )
	);

	wp_add_inline_script(
		'myplugin-map',
		'const mypluginMap = ' . wp_json_encode( array( 'apiBase' => esc_url_raw( rest_url( 'myplugin/v1' ) ) ) ) . ';',
		'before'
	);
}

Attaching an 'after' inline script to a script that uses the 'defer' strategy makes WordPress fall back to blocking loading for it; use the 'before' position to keep deferral intact.

Common problems and fixes · 4

Why doesn't my script show up on the page at all?

wp_enqueue_script() only calls $wp_scripts->enqueue(), which flags the handle for later printing; the actual tag is emitted separately when wp_head or wp_footer runs. Calling the function too late, or outside a hook WordPress actually fires before those points, means nothing gets printed. - Hook it to wp_enqueue_scripts for the front end. - Hook it to admin_enqueue_scripts for wp-admin. - Hook it to login_enqueue_scripts for wp-login.php.

Why did calling wp_enqueue_script() a second time not update my src or dependencies?

The source only runs $wp_scripts->add() when $src is truthy on that call. If you call the function again for the same handle with an empty $src, it skips registration entirely and just enqueues whatever was registered the first time, matching the 'does NOT overwrite' behavior noted in the description.
Deregister first if you need a different source:
wp_deregister_script( 'my-handle' ); wp_enqueue_script( 'my-handle', $new_src );

Why does passing true as the fifth argument make my strategy and fetchpriority disappear?

The source checks if ( ! is_array( $args ) ) { $args = array( 'in_footer' => (bool) $args ); }, so any non-array value you pass is collapsed down to just an in_footer flag; 'strategy' and 'fetchpriority' are never set. - Pass an array instead: array( 'in_footer' => true, 'strategy' => 'defer' ).

Why doesn't a handle like 'my-script?ver=2' register the way I expect?

The function splits the handle on '?' with explode() and registers the script under only the part before the question mark, but it enqueues using the original, unsplit $handle you passed in. If those two strings differ, wp_scripts()->enqueue() looks for a registered handle that was never actually added under that exact string. - Avoid '?' in handles unless you deliberately rely on this legacy splitting behavior.

Alternatives and related functions

wp_register_script
When you want to register a script now but decide later, conditionally, whether to actually enqueue it.
wp_deregister_script
When you need to replace or remove a script that was already registered under the same handle before re-adding it.
wp_add_inline_script
When you need to attach a small block of inline JavaScript before or after a script this function already queued.
wp_enqueue_style
When the asset you are loading is a stylesheet rather than a script.

Performance profile

How much work a call to wp_enqueue_script() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class
Trivial

Touches nothing outside its own arguments.

Scaling
Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions
19–47

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 47.

Plugin surface
None

Nothing here hands control to plugin code.

Called by
50

50 places in core call this, so the cost is paid more often than your own code shows.

What one call costs · 5 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_enqueue_script() can have, taken from its control-flow graph on PHP 8.5.

WhenInstructionsCalls it makes
empty($args)19_wp_scripts_maybe_doing_it_wrong(), wp_scripts(), ->enqueue()
empty($args)27–32_wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->enqueue()
!empty($args)34–39_wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), _wp_scripts_add_args_data(), ->enqueue()
empty($args)35–40_wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->add(), ->enqueue()
!empty($args)42–47_wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->add(), _wp_scripts_add_args_data(), ->enqueue()

Across PHP versions

Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 47 instructions, 19–47 executed per call, 5 branches. The work does not change between versions.

An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.

Uses · 3

Used by · 50

Show all 50

Source code

View on Trac View on GitHub 

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 ) ) {		/** @var array{ 0: non-empty-string, 1?: string } $_handle */		$_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 ) ) {			_wp_scripts_add_args_data( $wp_scripts, $_handle[0], $args );		}	} 	$wp_scripts->enqueue( $handle );}

Changelog

Introduced in 2.1.0. Unchanged from 6.7.7 through 7.1.0.

  1. 6.7.7
  2. 6.8.8
  3. 6.9.7
  4. 7.0.4
  5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

7.0.0
The $module_dependencies parameter of type string[] was added to the $args parameter of type array.from the docblock
6.9.0
The $fetchpriority parameter of type string was added to the $args parameter of type array.from the docblock
6.3.0
The $in_footer parameter of type boolean was overloaded to be an $args parameter of type array.from the docblock
2.1.0
Introduced.from the docblock

About this page

Parsed data
Generated from the wordpress-develop 7.0.4 tag, from src/wp-includes/functions.wp-scripts.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.
Corrections
Something wrong on this page? Report it and it gets fixed in the next regeneration.