What Are Wordpress Enqueues and Why Should You Use Them?


When developing a static site it's very common to put all of your styles and scripts directly in the header and footer and for quite a while I used to do this for Wordpress sites as well.

<link rel="stylesheet" href="<?php echo get_stylesheet_directory_uri(); ?>/css/some-style.css">
<script src="<?php echo get_template_directory_uri(); ?>/js/some-script.js">

However, while this will work most of the time it can cause trouble down the line (e.g. theme/plugin conflicts) and there is a better way to do it with added benefits - namely Wordpress enqueuing.

I this post we'll look at two enqueuing functions: wp_enqueue_style and wp_enqueue_script for adding styles and scripts respectively.

Enqueuing styles

The Wordpress docs provides us with the following:

wp_enqueue_style( string $handle, string $src = false, array $deps = array(), string|bool|null $ver = false, string $media = 'all' )

Which on first glance is a lot to take in so lets break it down.

wp_enqueue_style takes up to 5 arguments with only the first being required. These are:

$handle : Unique name of the stylesheet

$src : Path to the stylesheet

$deps : An array of any dependencies the stylesheet needs (so they can load first)

$ver : A version number for caching (we'll come to this later)

$media : The type of media for the stylesheet (e.g. screen, print)

So a typical enqueue for some a stylesheet might look something like this (leaving out unneeded arguments):

/* Load some style */
wp_enqueue_style('some-style', get_stylesheet_directory_uri() . '/css/some-style.css');

To enqueue the base stylesheet for the theme we don't even need the full file path. We can just reference the stylesheet directory:

/* Load style.css */
wp_enqueue_style( 'my-theme', get_stylesheet_uri() );

This by itself isn't enough to add the styles as we'll need to hook into a wordpress function to get them added. But we'll come to that shortly.

Enqueuing Scripts

If you've understood the enqueuing styles section then wp_enqueue_script is pretty much the same. The only different is this time we have a few different arguments to pass to the function.

The Wordpress docs provides us with the following:

wp_enqueue_script( string $handle, string $src = false, array $deps = array(), string|bool|null $ver = false, bool $in_footer = false )

$handle : Unique name of the script

$src : Path to the script

$deps : An array of any dependencies the script needs (so they can load first)

$ver : A version number for caching (I promise we will come to this)

$in_footer : Whether the script loads in the head or footer (default is false meaning it loads in the header)

Here is an example of a simple enqueue to load a script:

/* Load some script */
wp_enqueue_script( 'some-script', get_template_directory_uri() . '/js/jquery.some-script.js');

For this particular script we can see from its filename that it relies on jQuery so lets add that as a dependency:

/* Load some script */
wp_enqueue_script( 'some-script', get_template_directory_uri() . '/js/jquery.some-script.js', array('jquery'));

You may be wondering how jQuery is being loaded here. Wordpress has a library of Core Registered Scripts which you can call on at any time rather than loading your own.

Note: Loading jQuery in this way means it will run in noConflict mode which helps prevent issues with other scripts using the $ alias. However, this means you cannot the shorthand $ but must use the full jQuery instead. Alternatively, you could just place all your jQuery inside a noConflict wrapper:

jQuery( document ).ready( function( $ ) {
    // $ will now work as an alias inside of this function
    [ code goes here ]
} );

Finally, lets change the 'in_footer' argument so that the script loads in the footer to improve performance. To do this we'll just simply set the final argument to true.

/* Load some script */
wp_enqueue_script( 'some-script', get_template_directory_uri() . '/js/jquery.some-script.js', array('jquery'), false, true);

But what about that fourth argument 'ver'? Well, this finally leads us on to...


Both wp_enqueue_style and wp_enqueue_script allow for a query string to be added to a url to help with cache busting. By default, the Wordpress version number is automatically added to all styles and scripts which functions as a simple versioning system. You may notice that when you inspect your assets in the browser they look like this:

<link rel="stylesheet" href="http://www.yourwebsite.com/wp-content/themes/yourtheme/css/some-style.css?ver=3.5.1">
<script src="http://www.yourwebsite.com/wp-content/themes/yourtheme/js/some-script.js?ver=3.5.1">

This is useful because when Wordpress gets updated the query string will change and break a browser's cache, meaning anyone visiting the site will now get a brand new version of all resources.

The problem arises when you updated some assets before a new version of Wordpress comes out. Now people will still see the old version until the cache expires or gets cleared (for example by force refreshing your browser). This is where custom versioning comes in. You just simply pass a string to the $ver argument.

/* Load some script */
wp_enqueue_script( 'some-script', get_template_directory_uri() . '/js/some-script.js', array('jquery'), 0.1, true);

Which outputs:

<script src="http://www.yourwebsite.com/wp-content/themes/yourtheme/js/some-script.js?ver=0.1">

You can use whatever string you like for versioning, in this case we've implemented a simple stepping system (e.g. 0.1, 0.2), but you could use the current date, unix time or any other versioning system you like.

Taking things a bit further, PHP has a handy function called filemtime which returns a timestamp when a file was modified. If you pass this output to the $ver parameter then it will break the cache every time you make a change to that particular file. You can see an example of how to do this over at wordimpress.com

Putting it all together

As mentioned earlier, for Wordpress to recognise our enqueues we need to hook our functions. The easiest way to do this is to place everything in a function (both styles and scripts) and hook it into the wp_enqueue_scripts action.

function theme_name_scripts() {
  wp_enqueue_style('some-style', get_stylesheet_directory_uri() . '/css/some-style.css');
  wp_enqueue_script( 'some-script', get_template_directory_uri() . '/js/some-script.js', array('jquery'), 0.1, true);
add_action( 'wp_enqueue_scripts', 'theme_name_scripts');