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
- Source
wp-includes/functions.wp-scripts.php:366
Registers a script under a handle if a source URL is given, then queues it for output, accepting either a boolean or an $args array for footer placement, loading strategy, and fetch priority. Because registering only happens when $src is truthy, calling it again on an already-registered handle without a src just re-enqueues without changing dependencies or version. Scripts queued this way are only printed later by WP_Scripts through the wp_head or wp_footer hooks, so the call itself has to happen no later than wp_enqueue_scripts, admin_enqueue_scripts, or login_enqueue_scripts.
Enqueues a script.
Description
Registers the script if $src provided (does NOT overwrite), and enqueues it.
Compatibility
- WordPress
- since 6.9.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 additional script loading strategies. 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()$strategystringOptional. 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.
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 front-end script with a defer loading strategy
A theme or plugin wants a script that highlights the price meta stored on post 2, loaded with the 'defer' strategy added to $args.
add_action( 'wp_enqueue_scripts', 'wppaste_enqueue_price_script' );
function wppaste_enqueue_price_script() {
wp_enqueue_script(
'wppaste-price-highlight',
'https://example.com/wp-content/plugins/wppaste-demo/price-highlight.js',
array(),
'1.0.3',
array(
'strategy' => 'defer',
'in_footer' => true,
)
);
$price = get_post_meta( 2, 'price', true );
echo esc_html( sprintf( 'Script queued: %s. Post 2 price meta: %s', wp_script_is( 'wppaste-price-highlight', 'enqueued' ) ? 'yes' : 'no', $price ) );
}The 'strategy' and 'fetchpriority' keys inside $args only work when $args is passed as an array, not a boolean.
Load a script only on the posts list screen in wp-admin
A plugin needs a small script on edit.php only, added the older way with a boolean fifth argument for footer placement.
add_action( 'admin_enqueue_scripts', 'wppaste_enqueue_admin_list_script' );
function wppaste_enqueue_admin_list_script( $hook_suffix ) {
if ( 'edit.php' !== $hook_suffix ) {
return;
}
wp_enqueue_script(
'wppaste-post-list-tweak',
'https://example.com/wp-content/plugins/wppaste-demo/post-list-tweak.js',
array( 'jquery' ),
false,
true
);
echo '<div class="notice notice-info"><p>' . esc_html( 'wppaste-post-list-tweak queued for the Posts screen footer.' ) . '</p></div>';
}Visit Posts in wp-admin to see the notice; on any other admin screen the hook returns early and nothing prints.
Common problems and fixes · 4
- Why doesn't my script show up on the page at all?
- Why did calling wp_enqueue_script() a second time not update my src or dependencies?
- Why does passing true as the fifth argument make my strategy and fetchpriority disappear?
- Why doesn't a handle like 'my-script?ver=2' register the way I expect?
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
- Scaling
- Constant
- Instructions
- 19–69
- Plugin surface
- None
- Called by
- 50
Touches nothing outside its own arguments.
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 69.
Nothing here hands control to plugin code.
50 places in core call this, so the cost is paid more often than your own code shows.
What one call costs · 9 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.
| When | Instructions | Calls it makes |
|---|---|---|
empty($args) | 19 | _wp_scripts_maybe_doing_it_wrong(), wp_scripts(), ->enqueue() |
empty($args) | 31–36 | _wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->enqueue() |
| always | 38–45 | _wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->add_data(), ->enqueue() |
empty($args) | 39–44 | _wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->add(), ->enqueue() |
| always | 46–53 | _wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->add(), ->add_data(), ->enqueue() |
| always | 47–54 | _wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->add_data(), ->add_data(), ->enqueue() |
| always | 55–62 | _wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->add(), ->add_data(), ->add_data(), ->enqueue() |
!empty($args) | 56–61 | _wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->add_data(), ->add_data(), ->add_data(), ->enqueue() |
!empty($args) | 64–69 | _wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->add(), ->add_data(), ->add_data(), ->add_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: 69 instructions, 19–69 executed per call, 7 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 · 2
- _wp_scripts_maybe_doing_it_wrong()Helper function to output a _doing_it_wrong message when applicable.
- wp_scripts()Initializes $wp_scripts if it has not been set.
Used by · 50
- Custom_Background::admin_load()Sets up the enqueue for the CSS & JavaScript files.
- Custom_Image_Header::js_includes()Sets up the enqueue for the JavaScript files.
- Featured_Content::enqueue_scripts()Enqueues the tag suggestion script.
- Twenty_Fourteen_Ephemera_Widget::enqueue_scripts()Enqueues scripts.
- Twenty_Twenty_One_Customize_Color_Control::enqueue()Enqueues control related scripts/styles.
- Twenty_Twenty_One_Dark_Mode::customize_controls_enqueue_scripts()Enqueues scripts for the customizer.
- Twenty_Twenty_One_Dark_Mode::editor_custom_color_variables()Enqueues editor custom color variables & scripts.
- WP_Admin_Bar::initialize()Initializes the admin bar.
- WP_Block::render()Generates the render output for the block.
- WP_Customize_Color_Control::enqueue()Enqueue scripts/styles for the color picker.
- WP_Customize_Cropped_Image_Control::enqueue()Enqueue control related scripts/styles.
- WP_Customize_Header_Image_Control::enqueue()
Show all 50
- WP_Customize_Manager::customize_preview_init()Prints JavaScript settings.
- WP_Customize_Manager::enqueue_control_scripts()Enqueues scripts for customize controls.
- WP_Customize_Nav_Menus::customize_preview_enqueue_deps()Enqueues scripts for the Customizer preview.
- WP_Customize_Nav_Menus::enqueue_scripts()Enqueues scripts and styles for Customizer pane.
- WP_Customize_Selective_Refresh::enqueue_preview_scripts()Enqueues preview scripts.
- WP_Customize_Widgets::customize_preview_enqueue()Enqueues scripts for the Customizer preview.
- WP_Customize_Widgets::enqueue_scripts()Enqueues scripts and styles for Customizer panel and export data to JavaScript.
- WP_Internal_Pointers::enqueue_scripts()Initializes the new feature pointers.
- WP_Privacy_Policy_Content::notice()Adds a notice with a link to the guide when editing the privacy policy page.
- WP_Widget_Custom_HTML::enqueue_admin_scripts()Loads the required scripts and styles for the widget control.
- WP_Widget_Media::enqueue_admin_scripts()Loads the required scripts and styles for the widget control.
- WP_Widget_Media_Audio::enqueue_admin_scripts()Loads the required media files for the media manager and scripts for media widgets.
- WP_Widget_Media_Audio::enqueue_preview_scripts()Enqueue preview scripts.
- WP_Widget_Media_Gallery::enqueue_admin_scripts()Loads the required media files for the media manager and scripts for media widgets.
- WP_Widget_Media_Image::enqueue_admin_scripts()Loads the required media files for the media manager and scripts for media widgets.
- WP_Widget_Media_Video::enqueue_admin_scripts()Loads the required scripts and styles for the widget control.
- WP_Widget_Media_Video::enqueue_preview_scripts()Enqueue preview scripts.
- WP_Widget_Text::enqueue_admin_scripts()Loads the required scripts and styles for the widget control.
- _WP_Editors::enqueue_scripts()
- _wp_get_iframed_editor_assets()Collect the block editor assets that need to be loaded into the editor's iframe.
- add_thickbox()Enqueues the default ThickBox js and css.
- do_accordion_sections()Meta Box Accordion Template Function.
- enqueue_comment_hotkeys_js()Enqueues comment shortcuts jQuery script.
- enqueue_editor_block_styles_assets()Function responsible for enqueuing the assets required for block styles functionality on the editor.
- media_upload_gallery()Retrieves the legacy media uploader form in an iframe.
- register_and_do_post_meta_boxes()Registers the default post meta boxes, and runs the `do_meta_boxes` actions.
- render_block_core_comments()Renders the `core/comments` block on the server.
- render_block_core_post_comments_form()Renders the `core/post-comments-form` block on the server.
- the_block_editor_meta_boxes()Renders the meta boxes forms.
- the_custom_header_markup()Prints the markup for a custom header.
- twenty_twenty_one_scripts()Enqueues scripts and styles.
- twentyeleven_admin_enqueue_scripts()Properly enqueues styles and scripts for our theme options page.
- twentyeleven_customize_preview_js()Binds JS handlers to make Customizer preview reload changes asynchronously.
- twentyfifteen_customize_control_js()Binds JS listener to make Customizer color_scheme control.
- twentyfifteen_customize_preview_js()Binds JS handlers to make the Customizer preview reload changes asynchronously.
- twentyfifteen_scripts()Enqueues scripts and styles.
- twentyfourteen_customize_preview_js()Binds JS handlers to make Customizer preview reload changes asynchronously.
- twentyfourteen_scripts()Enqueues scripts and styles for the front end.
Source code
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 );}Changelog
Introduced in 2.1.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
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 6.9.7 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.