Adding Scripts and Styles to WordPress Correctly with Enqueueing

Many of us use styles to alter the look of our website, and scripts to enhance functionality. It is important to note however, that the way you add these scripts to WordPress is just as important as the content of these files. Instead of plopping them into the header or footer file we need to use WordPress’ enqueue functionality.

In this article, I’ll show you how to add scripts and styles to your themes and plugins, whether you are creating something on the front-end or in the backend.

We’ll cover:

What is Enqueuing
Enqueuing: The Bottom Line
Enqueuing Assets Correctly
Enqueuing in Detail
Asset Registration
Removing Scripts and Styles

What is Enqueueing?

Enqueueing is a CMS-friendly way of adding scripts and styles to WordPress websites. Multiple plugins you have may use jQuery and other shared scripts. If each plugin linked to these assets separately, chaos would ensue and all your JavaScript could stop working.

By enqueueing scripts you are telling WordPress about the assets you want to add and it will take care of actually linking to them in the header and footer. You can even specify the dependencies of your scripts and styles and WordPress will add them in the correct order.

It takes all the information from what is needed by the core, by your theme and your plugins, creates a list of scripts and styles needed, and outputs them in the correct location.

Enqueuing: The Bottom Line

No matter how you attach your assets, the end result will be a <script> or a <link> tag somewhere in your website’s HTML. The example below shows three scripts and two styles loaded on a website:

Functionality-wise, this is perfectly fine ,but let’s not forget that WordPress is tasked with a bit more than what I’ve shown above. There may be a few other scripts and styles hanging around. Since the order you include scripts and styles in matters a lot, if you just start putting them in your theme’s header or footer you may get lost very soon.

In addition, the majority of these scripts are not visible in the your theme’s PHP code. All the scripts WordPress and other plugins need are added via the wp_head() and wp_footer() functions.

Enqueueing Assets Correctly

Enqueueing is a way to let WordPress know about your scripts and their dependencies. Based on this, WordPress works out the placement of the script for you. Since this is all done by code you won’t have to worry about rearranging scripts when you need to add a new one. Let’s go through the scripts in the previous section, adding them by enqueueing:

This code should be placed in the functions.php file of our theme, child theme, or in a plugin file. Note that both scripts and styles are enqueued by attaching a function to the wp_enqueue_scripts hook.

The first two things I enqueued were our styles. I defined our theme style first, even though it depends on the reset style. This is not a problem since I defined this dependency in the third parameter. The first parameter is the unique name of the asset, the second is its location.

The third asset I’ve added is the excellent Owl Carousel. In the third parameter I’ve specified jQuery as a dependency. I do not need to enqueue this myself because it is built into WordPress. Take a look at the WordPress Codex for a list of included scripts.

Finally, I include the theme script. Our script depends on jQuery and Owl Carousel. In reality you could get away with just defining Owl Carousel as the dependency. Since jQuery is a dependency for Owl Carousel it would be included before it in any case. That said, I like to state my dependencies fully, it gives me more information when looking at the code.

The last piece of the puzzle is making sure that our theme script is loaded in the footer. This can be done by defining the fifth parameter as true. The fourth parameter is an optional version number which I’ve set to 1.0.

Enqueueing in Detail

Now that you’ve seen an example, let’s get our hands dirty and look at all the functions and parameters available to us.

We used two functions: wp_enqueue_script() and wp_enqueue_style(). They both take five parameters, sharing the first four:

handle: This is the name of your script or style. It is best to use only lowercase letters and dashes here, and make sure to use a unique name.
source: The URL of your script or style. Make sure to use functions like get_template_directory_uri() or plugins_uri().
dependencies: An array of handles to assets which your script or style depends on. These will be loaded before your enqueued script.
version: A version number which will be appended to the query. This ensures that the user receives the correct version, regardless of caching.
in_footer: This parameter is only available for scripts. If set to true the script is loaded through wp_footer() at the bottom of your page.
media: This parameter is for styles, it allows you to specify the type of media the style should be displayed for. For example: screen, print, handheld, etc.

Hopefully the explanation of the parameters made our example in the previous section that much clearer. You can now start playing around with your own styles and scripts.

Asset Registration

There are actually two steps to adding an asset, but the enqueueing function can get it done in one go. Technically scripts and styles are first registered and then enqueued. Registration lets WordPress know about your assets, while enqueuing actually adds them to the page. Here’s an alternative way to add our Owl Carousel:

So why do this in two steps when one is enough? The answer is that in some cases you don’t register the script in the same place you enqueue it. A good example is shortcodes. Suppose a shortcode you create requires some Javascript. If you enqueue it by attaching it to wp_enqueue_scripts hook it will be loaded on every request, even if the shortcode isn’t used.

The answer is to register the script using the wp_enqueue_scripts hook, but enqueue it in the shortcode function. This will load it only when the shortcode is actually used. If the shortcode is used multiple times the script will only be included once so we’ve covered all the bases.

The wp_register_scripts() and wp_register_styles() functions share the same parameters as their enqueuing brethren. The only difference is the the enqueue functions allow you to specify only the handle as long as that handle has been registered.

Removing Scripts And Styles

WordPress provides dequeueing and deregistering functions for both scripts and styles.

wp_deregister_script()
wp_deregister_style()
wp_dequeue_script()
wp_dequeue_style()

These function allow us to remove assets modularly. The following example shows how jQuery can easily be removed and replaced by a more recent version.

That being said, it is almost never a good idea to replace jQuery with a new version. WordPress is built to work as smoothly as possible with the version added to it by default. Replacing it should not be taken lightly.

Summing Up

Hopefully, you now see why enqueueing is such an important process. It takes the burden of dependency maintenance off your shoulders and allows you to add your scripts in a modular and manageable way.

Enqueueing is required for all WordPress plugins and themes. Your product (free or premium) will not be accepted into the WordPress repository and many premium marketplaces without it. It forms the basis of “playing nice with others” and should be followed by every developer.