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
- Source
wp-includes/functions.wp-scripts.php:359
Queues a script handle for output, registering it with $src, $deps, $ver, and $args first if that handle hasn't already been registered. Registration only happens when $src is non-empty, and it never overwrites a handle registered earlier by core or another plugin. Since 6.3.0, $args can carry a 'strategy' of defer or async in addition to the older in_footer boolean, so check which shape your target version expects before passing it.
Enqueues a script.
Description
Registers the script if $src provided (does NOT overwrite), and enqueues it.
Compatibility
- WordPress
- since 6.3.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.
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 script with a defer or async loading strategy
Register and queue a script that uses the strategy option added to the $args array in WordPress 6.3.0.
wp_enqueue_script(
'wppaste-example-async',
'https://example.com/assets/example.js',
array(),
'2.0.1',
array(
'strategy' => 'async',
'in_footer' => true,
)
);
$wp_scripts = wp_scripts();
$dependency = $wp_scripts->registered['wppaste-example-async'];
echo 'Registered src: ' . esc_html( $dependency->src ) . "\n";
echo 'Loading strategy: ' . esc_html( $dependency->extra['strategy'] ) . "\n";
echo 'Placed in footer group: ' . ( ! empty( $dependency->extra['group'] ) ? 'yes' : 'no' ) . "\n";
echo 'Enqueued: ' . ( wp_script_is( 'wppaste-example-async', 'enqueued' ) ? 'yes' : 'no' );The script's actual src file does not need to exist for registration and enqueueing to succeed; the browser only 404s on the asset itself.
Only enqueue a script on single post pages
Hook the enqueue call to wp_enqueue_scripts so it only fires for singular posts, then confirm it ran from the footer.
add_action( 'wp_enqueue_scripts', function() {
if ( is_singular( 'post' ) ) {
wp_enqueue_script(
'theme-post-highlighter',
get_theme_file_uri( 'assets/post-highlighter.js' ),
array( 'jquery' ),
'1.0.0',
array(
'strategy' => 'defer',
'in_footer' => true,
)
);
}
} );
add_action( 'wp_footer', function() {
echo '<p>' . esc_html( wp_script_is( 'theme-post-highlighter', 'enqueued' ) ? 'Highlighter script queued for this post.' : 'Highlighter script not queued here.' ) . '</p>';
} );Load the front end permalink for post ID 1 to see the footer message; visiting any other template shows the 'not queued' message instead.
Common problems and fixes · 3
- Why did calling wp_enqueue_script with a new $src on an already-registered handle not change the script's source?
- Why am I seeing a 'doing it wrong' notice when I call wp_enqueue_script?
- Why did passing an $args array not put my script in the footer?
Why did calling wp_enqueue_script with a new $src on an already-registered handle not change the script's source?
Registration only happens inside this function when $src is truthy, and the underlying WP_Dependencies::add() call it delegates to refuses to overwrite a handle that's already registered under that name. If core, a plugin, or an earlier call already registered that handle, your new $src is silently ignored.
Why am I seeing a 'doing it wrong' notice when I call wp_enqueue_script?
The function opens by calling _wp_scripts_maybe_doing_it_wrong(), which flags calls made before the wp_enqueue_scripts, admin_enqueue_scripts, or login_enqueue_scripts action has fired for the current request.
Why did passing an $args array not put my script in the footer?
The footer placement only happens when $args is an array containing a truthy 'in_footer' key; the source checks !empty( $args['in_footer'] ) before calling add_data( ..., 'group', 1 ). Passing an array without that key, or passing a strategy-only array, leaves the script in the default head position.
Alternatives and related functions
wp_register_script- When you want to make a script handle available for other code to depend on without printing it yet, and enqueue it separately once it's actually needed on the page.
wp_deregister_script- When you need to replace a script that's already been registered under the same handle, since wp_enqueue_script itself will not overwrite an existing registration.
wp_script_is- When you need to check whether a handle is already registered, enqueued, or done before deciding whether to call wp_enqueue_script again.
wp_add_inline_script- When you need to attach inline JavaScript immediately before or after the script handle that wp_enqueue_script queues.
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–58
- 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 58.
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 · 7 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) | 29–34 | _wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->enqueue() |
| always | 36–43 | _wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->add_data(), ->enqueue() |
empty($args) | 37–42 | _wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->add(), ->enqueue() |
| always | 44–51 | _wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->add(), ->add_data(), ->enqueue() |
!empty($args) | 45–50 | _wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->add_data(), ->add_data(), ->enqueue() |
!empty($args) | 53–58 | _wp_scripts_maybe_doing_it_wrong(), wp_scripts(), explode(), ->add(), ->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: 58 instructions, 19–58 executed per call, 6 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()Enqueue the tag suggestion script.
- Twenty_Fourteen_Ephemera_Widget::enqueue_scripts()Enqueue scripts.
- Twenty_Twenty_One_Customize_Color_Control::enqueue()Enqueue 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 enqueue styles and scripts for our theme options page.
- twentyeleven_customize_preview_js()Bind 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()Enqueue scripts and styles.
- twentyfourteen_customize_preview_js()Bind JS handlers to make Customizer preview reload changes asynchronously.
- twentyfourteen_scripts()Enqueue 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'] ); } } $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.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.8.8 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.