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

User Contributed Notes

1. Skip to note 29 content

   Andrija Naglic 9 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 70You must log in to vote on the helpfulness of this note

   Never worry about cache again!

   This is a little trick I’ve picked up along the way.
   The version of the .js and .css files is made from the time of it’s last update.

   /**
    * Never worry about cache again!
    */
   function my_load_scripts($hook) {
   
   	// create my own version codes
   	$my_js_ver  = date("ymd-Gis", filemtime( plugin_dir_path( __FILE__ ) . 'js/custom.js' ));
   	$my_css_ver = date("ymd-Gis", filemtime( plugin_dir_path( __FILE__ ) . 'style.css' ));
   	
   	// 
   	wp_enqueue_script( 'custom_js', plugins_url( 'js/custom.js', __FILE__ ), array(), $my_js_ver );
   	wp_register_style( 'my_css', 	plugins_url( 'style.css', 	 __FILE__ ), false,   $my_css_ver );
   	wp_enqueue_style ( 'my_css' );
   
   }
   add_action('wp_enqueue_scripts', 'my_load_scripts');

   That way, you will always use the cached versions, except in case the files were changed in the meanwhile, which is the most optimum scenario.
2. Skip to note 30 content

   bcworkz 9 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 41You must log in to vote on the helpfulness of this note

   When you enqueue script that is dependent on jQuery, note that the jQuery in WordPress runs in noConflict mode, which means you cannot use the common $ alias. You must use the full jQuery instead. Alternately, place your code using the $ shortcut inside a noConflict wrapper.

   jQuery( document ).ready( function( $ ) {
       // $() will work as an alias for jQuery() inside of this function
       [ your code goes here ]
   } );
3. Skip to note 31 content

   Barbara Ford 10 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 30You must log in to vote on the helpfulness of this note

   Using a Hook

   Enqueue both scripts and styles from a single action hook.

   /**
    * Proper way to enqueue scripts and styles.
    */
   function wpdocs_theme_name_scripts() {
   	wp_enqueue_style( 'style-name', get_stylesheet_uri() );
   	wp_enqueue_script( 'script-name', get_template_directory_uri() . '/js/example.js', array(), '1.0.0', true );
   }
   add_action( 'wp_enqueue_scripts', 'wpdocs_theme_name_scripts' );
4. Skip to note 32 content

   Barbara Ford 10 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 21You must log in to vote on the helpfulness of this note

   Link a Theme Script Which Depends on jQuery

   JavaScript files included in themes often require another JavaScript file to be loaded in advance to use its functions or variables. Using the $deps parameter, the wp_enqueue_script() and wp_register_script() functions allows you to mark dependencies when registering a new script. This will cause WordPress to automatically link these dependencies to the HTML page before the new script is linked. If the handles of these dependencies are not registered, WordPress will not link the new script. This example requires the jQuery library for the custom_script.js theme script:

   /**
    * Enqueue a script with jQuery as a dependency.
    */
   function wpdocs_scripts_method() {
   	wp_enqueue_script( 'custom-script', get_stylesheet_directory_uri() . '/js/custom_script.js', array( 'jquery' ) );
   }
   add_action( 'wp_enqueue_scripts', 'wpdocs_scripts_method' );
5. Skip to note 33 content

   Andrei Surdu 9 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 16You must log in to vote on the helpfulness of this note

   I want to add a note to bcworkz comment. When using jquery, in general, this is how the code in a file should be formatted:

   (function( $ ) {
   
   	"use strict";
   	
   	// javascript code here. i.e.: $(document).ready( function(){} ); 
   
   })(jQuery);

   It’s a common practice that ensures jQuery runs in no conflict mode and in strict mode.
   
   Strict mode helps out in a couple ways:

   • It catches some common coding bloopers, throwing exceptions.
   • It prevents, or throws errors, when relatively “unsafe” actions are taken (such as gaining access to the global object).
   • It disables features that are confusing or poorly thought out.
6. Skip to note 34 content

   Barbara Ford 10 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 8You must log in to vote on the helpfulness of this note

   Link the script.aculo.us Library

   The following is an example of basic usage which links the script.aculo.us library already included and registered by WordPress with the scriptaculous handle.

   /**
    * Enqueue script.aculo.us.
    *
    * Tha callback is hooked to 'wp_enqueue_script' to ensure the script is only enqueued on the front-end.
    */
   function my_scripts_method() {
       wp_enqueue_script( 'scriptaculous' );
   }
   add_action( 'wp_enqueue_scripts', 'my_scripts_method' );

   The above example links the script.aculo.us library only on the front-end. If the library was needed within the administration screens, you could use the admin_enqueue_scripts action hook instead, however, this would enqueue it on all the administration screens, which often leads to plugin/core conflicts, ultimately breaking the WordPress administration screens experience. Instead, you should only link it on the individual screens you need it, see the Link Scripts Only on a Plugin Administration Screen section for an example of that.
7. Skip to note 35 content

   Pratik Shrestha 8 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

   When registering and enqueueing scripts, you don’t need to call wp_register_script() and wp_enqueue_script(). Just call wp_enqueue_script().
   This:

   wp_register_script ( 'custom-script', get_template_directory_uri() . '/js/custom-script.js' );
   wp_enqueue_script ( 'custom-script' );

   Should simply be:

   wp_enqueue_script ( 'custom-script', get_template_directory_uri() . '/js/custom-script.js' );

   Only register if you don’t know if you’re going to load it immediately.
8. Skip to note 36 content

   cgastrell 6 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

   Unmet dependencies will *NOT* be warned

   If dependencies (3rd argument) are not met, the script tag is just not printed and no warnings nor errors are shown.

   This doesn’t seem like a bug, just expected behavior. A mention about this on the docs would suffice to prevent misunderstandings.

   This example will never load /js/example.js

   /**
    * ... enqueue plugin scripts.
    */
   function load_plugin_scripts() {
       wp_enqueue_script(
   		'script-name',
   		plugin_dir_url( __FILE__ ) . '/js/example.js',
   		array('not-existant'),
   		'1.0.0',
   		true
   	);
   }
   add_action( 'wp_enqueue_scripts', 'load_plugin_scripts' );
9. Skip to note 37 content

   Michael Nelson 9 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note

   Because of the work on https://core.trac.wordpress.org/ticket/9346, it’s actually safe to call

   wp_enqueue_script

   after the hook “wp_enqueue_scripts” and before the footer, eg when rendering shortcodes or rendering a post’s body.
   Enqueueing stylesheets (css) in this same method has some issues though.
   Scribu gave an example of a shortcode enqueueing a script here: http://scribu.net/wordpress/conditional-script-loading-revisited.html
10. Skip to note 38 content

    Bink 5 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note

    An example of how to enqueue multiple styles and scripts which include the SRI (sub-resource integrity) tag. This is loosely based on this article, but I’ve tried to simplify the code somewhat, particularly given I may want to include and manage many scripts/styles.

    The important thing to note, is the handle specified when enqueuing a style/script, needs to match the handle referenced in the my_add_sri function. Also note, aside from the obvious SRI tag difference, the str_replace method used on scripts in the my_add_sri function, is different to that used on styles.

    /**
    * Load custom CSS and JavaScript.
    */
    add_action( 'wp_enqueue_scripts', 'wpdocs_my_enqueue_scripts' );
    function wpdocs_my_enqueue_scripts() : void {
        // Enqueue my styles.
        wp_enqueue_style( 'wpdocs-bootstrap-style', 'https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.5.2/css/bootstrap.min.css' );
        wp_enqueue_style( 'wpdocs-datatables-bootstrap-style', 'https://cdnjs.cloudflare.com/ajax/libs/datatables/1.10.21/css/dataTables.bootstrap4.min.css' );
        
        // Enqueue my scripts.
        wp_enqueue_script( 'wpdocs-bootstrap-bundle-script', 'https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.5.2/js/bootstrap.bundle.min.js', array(), null, true );
        wp_enqueue_script( 'wpdocs-datatables-bootstrap-script', 'https://cdnjs.cloudflare.com/ajax/libs/datatables/1.10.21/js/dataTables.bootstrap4.min.js', array(), null, true );
        wp_enqueue_script( 'wpdocs-jquery-datatables-script', 'https://cdnjs.cloudflare.com/ajax/libs/datatables/1.10.21/js/jquery.dataTables.min.js', array(), null, true );    
        
        // Add filters to catch and modify the styles and scripts as they're loaded.
        add_filter( 'style_loader_tag', __NAMESPACE__ . '\wpdocs_my_add_sri', 10, 2 );
        add_filter( 'script_loader_tag', __NAMESPACE__ . '\wpdocs_my_add_sri', 10, 2 );
    }
    
    /**
    * Add SRI attributes based on defined script/style handles.
    */
    function wpdocs_my_add_sri( $html, $handle ) : string {
        switch( $handle ) {
            case 'wpdocs-bootstrap-style':
                $html = str_replace( ' />', ' integrity="sha512-MoRNloxbStBcD8z3M/2BmnT+rg4IsMxPkXaGh2zD6LGNNFE80W3onsAhRcMAMrSoyWL9xD7Ert0men7vR8LUZg==" crossorigin="anonymous" />', $html );
                break;
            case 'wpdocs-datatables-bootstrap-style':
                $html = str_replace( ' />', ' integrity="sha512-PT0RvABaDhDQugEbpNMwgYBCnGCiTZMh9yOzUsJHDgl/dMhD9yjHAwoumnUk3JydV3QTcIkNDuN40CJxik5+WQ==" crossorigin="anonymous" />', $html );
                break;
            case 'wpdocs-bootstrap-bundle-script':
                $html = str_replace( '></script>', ' integrity="sha512-kBFfSXuTKZcABVouRYGnUo35KKa1FBrYgwG4PAx7Z2Heroknm0ca2Fm2TosdrrI356EDHMW383S3ISrwKcVPUw==" crossorigin="anonymous"></script>', $html );
                break;
            case 'wpdocs-datatables-bootstrap-script':
                $html = str_replace( '></script>', ' integrity="sha512-OQlawZneA7zzfI6B1n1tjUuo3C5mtYuAWpQdg+iI9mkDoo7iFzTqnQHf+K5ThOWNJ9AbXL4+ZDwH7ykySPQc+A==" crossorigin="anonymous"></script>', $html );
                break;
            case 'wpdocs-jquery-datatables-script':
                $html = str_replace( '></script>', ' integrity="sha512-BkpSL20WETFylMrcirBahHfSnY++H2O1W+UnEEO4yNIl+jI2+zowyoGJpbtk6bx97fBXf++WJHSSK2MV4ghPcg==" crossorigin="anonymous"></script>', $html );
                break;
        } 
        return $html;
    }

    • As I was trying to use the ‘new’ recommended CDN for Bootstrap 4.5.X (jsDelivr) and stumbled upon how exactly to figure out how to add the SRI tag, I can only commend your solution and the simplification you did to the original code. Thank you!

      Gwyneth Llewelyn 4 years ago
11. Skip to note 39 content

    Xedin Unknown 9 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

    This is not documented, but calling this function with $in_footer being `false` actually registers the script in general as a dependency that should be resolved and output, not just for header. Then, when outputting scripts enqueued for the footer, only the scripts that have not been included yet will be output. This leads to behaviour where a script that is enqueued supposedly in the header will appear in the footer if enqueued after the header has already been process. Therefore, $in_footer should actually read and be understood as $in_footer_only.
12. Skip to note 40 content

    Manny Fleurmond 8 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

    Because this and wp_enqueue_style uses WP_Scripts::enqueue(), which can take an array of handles as it’s first argument, you can also pass an array of handles into wp_enqueue_script/style:

    /**
     * Enqueue multiple handles
     */
    function enqueue_multiple() {
        wp_enqueue_script( array( 'backbone', 'jquery', 'iris' ) );
    }
    add_action( 'wp_enqueue_scripts', 'enqueue_multiple' );
13. Skip to note 41 content

    Yakovos Frountas 2 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

    This example is using the new technique of defer or async a script. Also one good practice for versioning of the file is to use the filemtime php native function in order to pass the last modified time of the file as a parameter to the cache.

    $url  = get_template_directory_uri() . '/js/functions.js';
    $time = filemtime( get_template_directory() . '/js/functions.js' );
    $args = array( 
        'in_footer' => true,
        'strategy'  => 'defer',
    );
    
    wp_enqueue_script( 'wpdocs-functions', $url, array(), $time, $args );
14. Skip to note 42 content

    Mário Valney 7 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    For who have the same question of @damiankaelgreen:

    In this case script is the file called in one HTML tag script which is used to define a client-side script (JavaScript).

    For include PHP files, please use get_template_part().
15. Skip to note 43 content

    Parth Dodiya 11 months ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    Clearing confusion between all three functions. wp_enqueue_script() , wp_register_script() , and wp_localize_script()

    wp_register_script()::
    Registers a script with WordPress.
    Does not load the script on the page.
    Useful when you want to define a script for later use with specific conditions or dependencies.
    Takes arguments like script handle (unique identifier), script path (URL or relative path to the file), and optional arguments like version number and dependencies on other scripts.

    wp_enqueue_script()::
    Enqueues a script that need to be loaded on the page.
    Can also register the script if it hasn’t been registered before.
    Useful for including scripts you need on a specific page or based on certain conditions (e.g., only on the front-end).
    Takes arguments like script handle (same as used with wp_register_script) and optional arguments like version number, dependencies, and placement (in the header or footer).
    Here’s a key difference:

    wp_enqueue_script can handle both registering and loading a script in one call.
    wp_register_script only registers the script for later use with wp_enqueue_script or another function that might need it.

    wp_localize_script()::
    Does not register or enqueue a script.
    Used to localize a registered script, meaning it injects PHP variables into the script as JavaScript objects.
    Useful for passing data from WordPress (PHP) to your JavaScript code.
    Takes arguments like script handle (of an already registered script), a variable name to hold the data in JavaScript, and the actual PHP data (array or object) you want to pass.

    In short,
    Use wp_register_script to define scripts for later use.
    Use wp_enqueue_script to load scripts on the page (can also register if needed).
    Use wp_localize_script to pass data from PHP to your registered JavaScript code.
16. Skip to note 44 content

    Anthony Hortin 8 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    See Also:

    wp_enqueue_style
17. Skip to note 45 content

    damiankaelgreen 8 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    This documentation should really do a better job defining what a “script” is… Because: is this function meant for enqueueing a .php or html script? No!

    That may seem obvious to a lot of developers, but if you are looking at this documentation, you should be getting some clarity as to what this function should be used for, so I’m writing this to help.

    Apparently, in this case, the term “script” is being used as a program that is not being evaluated by the server, but rather a program that needs to be passed to the client (and evaluated by the browser). Thus in this case, a PHP file that is expected to be evaluated by the server would not be considered a script (even though a lot of people might call it one) and thus it should not be included with wp_enqueue_script() , but included using require_once() or possibly include_once() instead.
18. Skip to note 46 content

    Rabby 7 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    This example link of custom stylesheet and script with file version version

    function custom_enqueue(){
        //wp_enqueue_style('string $handle', mixed $src, array $deps, mixed $ver, string $meida );
        wp_enqueue_style('customstyle', get_template_directory_uri() . '/css/fatblog.css', array(), '1.0.0', 'all' );
        //wp_enqueue_style('string $handle', mixed $src, array $deps, mixed $ver, bol $in_footer );
        wp_enqueue_script('customjs', get_template_directory_uri() . '/js/fatblog.js', array(), '1.0.0', 'true' );
    }
    add_action('wp_enqueue_scripts', 'custom_enqueue');
19. Skip to note 47 content

    turnipforest 4 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    The required CSS for jquery-ui-dialog does not come automatically!

    You must separately call wp_enqueue_style() with the registered handle “wp-jquery-ui-dialog”.
20. Skip to note 48 content

    indithemes 1 year ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    In some cases, you might want to add scripts as a module. In that case type="module" needs to be added to the tag. This can be done using the script_loader_tag filter hook.

    Modules are a newer feature of JS introduced in ES6 and has many advantages over conventional JS files especially if you are working on a large project. You can read about modules in official documentation.

    function wpdocs_load_module( $tag, $handle ) {
    	if ( 'wpdocs-script-handle' === $handle ) {
    		$tag = str_replace( '<script ', '<script type="module" ', $tag );
    	}
    
    	return $tag;
    }
    add_filter( 'script_loader_tag', 'wpdocs_load_module', 10, 2 );
21. Skip to note 49 content

    Hache_raw 9 months ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    Replace a parent theme JS (or CSS) entirely:

    function wpdocs_child_enqueue_scripts() {
    	if ( wp_script_is( 'parent-pagination-infinite', 'enqueued' ) ) {
    		wp_dequeue_script( 'parent-pagination-infinite' );
    		wp_enqueue_script( 'child-pagination-infinite', get_stylesheet_directory_uri() . '/pagination-infinite.js', array( 'child-theme-js' ), '1.0.0', true );
    	}
    
    }
    
    add_action( 'wp_enqueue_scripts', 'wpdocs_child_enqueue_scripts', 15 );
22. Skip to note 50 content

    Barbara Ford 10 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Link a Plugin Script That Depends on script.aculo.us

    This example is intended to be used within a plugin file to register and link a new plugin script that depends on the script.aculo.us library. See the example above for information about dependencies.

    /**
     * Enqueue script with script.aculo.us as a dependency.
     */
    function my_scripts_method() {
    	wp_enqueue_script( 'newscript', plugins_url( '/js/newscript.js' , __FILE__ ), array( 'scriptaculous' ) );
    }
    add_action( 'wp_enqueue_scripts', 'my_scripts_method' );
23. Skip to note 51 content

    Barbara Ford 10 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Link Scripts Only on a Plugin Administration Screen

    This example links a script only on a specific administration screen, as opposed to the scenario described in the paragraph below the code of the first example.

    <?php
    /**
     * Register the plugin script.
     */
    function wpdocs_plugin_admin_init() {
        // Register our script.
        wp_register_script( 'my-plugin-script', plugins_url( '/script.js', __FILE__ ) );
    }
    add_action( 'admin_init', 'wpdocs_plugin_admin_init' );
    
    /**
     * Add Administration screen for the plugin.
     */
    function wpdocs_plugin_admin_menu() {
        /* Add our plugin submenu and administration screen */
        $page_hook_suffix = add_submenu_page( 'edit.php',	// The parent page of this submenu.
    		__( 'My Plugin', 'my-textdomain' ),				// The submenu title.
    		__( 'My Plugin', 'my-textdomain' ),				// The screen title.
    		'manage_options', 								// The capability required for access to this submenu.
    		'my_plugin-options', 							// The slug to use in the URL of the screen.
    		'wpdocs_plugin_manage_menu' 					// The function to call to display the screen.
    	);
    
        /*
    	 * Use the retrieved $page_hook_suffix to hook the function that links our script.
    	 * This hook invokes the function only on our plugin administration screen,
    	 * see: https://developer.wordpress.org/reference/hooks/admin_print_scripts-hook_suffix/
    	 */
        add_action( "admin_print_scripts-{$page_hook_suffix}", 'wpdocs_plugin_admin_scripts');
    }
    add_action( 'admin_menu', 'wpdocs_plugin_admin_menu' );
    
    /**
     * Enqueue registered script in the admin.
     */
    function wpdocs_plugin_admin_scripts() {
        // Link our already registered script to a page.
        wp_enqueue_script( 'my-plugin-script' );
    }
    
    /**
     * Display callback for the plugin Administration screen.
     */
    function wpdocs_plugin_manage_menu() {
        // Display our administration screen.
    }
24. Skip to note 52 content

    Miguel Torres 6 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Not sure if this is the place to report it, but I believe that the Tiny MCE handle that appears on the “Default Scripts Included and Registered by WordPress” table is incorrect. It says tiny_mce, but according to the code that registers the Tiny MCE scripts (https://core.trac.wordpress.org/browser/trunk/src/wp-includes/script-loader.php?rev=45138#L56-L64) should be wp-tinymce.

    • Hi @mmtr86, Thanks, fixed!

      Jb Audras 6 years ago
25. Skip to note 53 content

    Uriahs Victor 4 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    When enqueuing a custom script file that you later want to add some inline JS to using wp_add_inline_script() . It’s always best that you have the custom script enqueuing in the footer by setting the last parameter in the function to true

    wp_enqueue_script( $handle, $src, $deps, $ver, true );
26. Skip to note 54 content

    vee 1 year ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    The list of libraries seems to be incomplete. For example `lodash`, `react` exists in WordPress vendor scripts but not list in this page, and there are more.

    To see full list, go to wp-includes/script-loader.php page.
27. Skip to note 55 content

    ilovecats7 5 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note

    The action hook used for loading scripts (wp_enqueue_scripts) is called in the head section of the document, so in order for the script to be loaded on the page, you MUST include the following on your page template:

    get_header();

    • This comment on the action hook stating you must include:

      get_header();

      This is inaccurate. This code fetches the header.php file. What must actually be included in the template is:

      wp_head();

      The confusion here is that most header files contain the wp_head(); hook.

      devdavi 5 years ago
28. Skip to note 56 content

    Drew Jaynes 9 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: -5You must log in to vote on the helpfulness of this note

    This is the place to report it. I’ve updated the table with your changes. Thanks!