WordPress comes pre-loaded with lots of common scripts – jQuery, Masonry, Underscore.js and more – and they’re all there waiting in the wings, ready for you to call them into action. Obviously no one wants their site bogged down with scripts they don’t need so WordPress registers them but it doesn’t automatically load them unless you tell it to with the wp_enqueue_script() function.

Enqueueing your scripts and stylesheets is the recommended way of adding scripts to your WordPress theme because in addition to giving you an easy way to access the list of pre-registered scripts, the enqueueing process helps prevent conflicts between themes and plugins. If you were to add jQuery to the head of your document with a script tag and then use a plugin that also uses jQuery, you may end up loading jQuery twice which is not ideal. Enqueueing your scripts prevents that.

One of the best things about enqueueing scripts in WordPress is that it makes it easy to include dependencies from the list of pre-registered scripts. The full list of scripts can be found in the WordPress function reference. All you have to do is pass the dependency’s handle into the arguments of wp_enqueue_script… and that’s it!

Enqueueing Scripts for jQuery UI

When I was recently adding a jQuery UI widget to a site, for example, instead of going to jqueryui.com and creating a custom package to only include the one or two things that I needed, downloading them and then writing out a bunch of script tags to link the various scripts to my document head, all I had to do was add ‘jquery’ and ‘jquery-ui-selectmenu’ to the array of dependencies for my custom javascript file and WordPress did the all of the work for me. Well, almost all of it…

WordPress loaded jQuery and all the jQuery UI scripts that were required by the select menu module (including menus, widget, mouse, position and more – so you can see why it’s nice to have WordPress handle this). But after a little digging, I discovered that it didn’t load the necessary css so my jQuery select menu lacked some of the default functionality like closing when a user clicks anywhere else on the page.

To solve this I grabbed jquery-ui.structure.css from jqueryui.com and enqueued that in functions.php as well and that solved the problem. I could’ve grabbed the other jQuery UI stylesheets (like one of their default themes) but I was writing my own styles so didn’t need anything but the jquery-ui.structure.css file to correct the functionality.

So while it’s kind of a pain that the required jQuery UI stylesheets aren’t pre-registered and included as dependencies, enqueueing jQuery UI was still mostly painless and definitely a quick way to get jQuery UI up and running on a WordPress site.

Here’s what the final wp_enqueue_scripts function looked like:

function my_add_theme_scripts() {
    // stylesheets
    wp_enqueue_style( 'jquery-structure-css', get_template_directory_uri() . '/jquery-ui.structure.css' );
    wp_enqueue_style( 'style', get_stylesheet_uri() );

    // scripts
    wp_register_script( 'custom.js', get_template_directory_uri() . '/js/custom.js', array('jquery', 'jquery-ui-selectmenu'), '1.0.0', true );
    wp_enqueue_script('custom.js');
}
add_action( 'wp_enqueue_scripts', 'my_add_theme_scripts' );

A Note about No-Conflict Mode

Because WordPress loads jquery in no-conflict mode, the $ alias will work only inside a document ready function with this syntax which comes from an article by Chris Coyier:

jQuery( document ).ready( function( $ ) {
    // do something
});

In order to use the $ alias outside of the document ready function, wrap it in this function instead:

( function( $ ) {
    // do something
} )( jQuery );

You can also use wp_deregister_script() to deregister the default jquery and add your own, but then you’ll lose the benefit of no-conflict mode.

Enqueueing Scripts Only When You Need Them

When you use wp_enqueue_scripts(), it’s easy to load scripts only on the page you need them. For example, if you have a script or a dependency that’s only required on the homepage (in this case, the jQuery UI Selectmenu dependencies), then you can register that script only on the homepage like so:

if ( is_front_page() ) :
    wp_register_script( 'custom.js', get_template_directory_uri() . '/js/custom.js', array('jquery', 'jquery-ui-selectmenu'), '1.0.0', true );
endif;

And you don’t get any unnecessary weight on the rest of your site.