Many of us use CSS to change the appearance of the website, and JavaScript to enhance or add functionality. However, there’s also significant importance to the method you add these assets in WordPress.
Instead of directly linking these files in the Header or Footer of your site, we should use the built-in WordPress functionality called enqueueing.
In this guide, I will explain how to add assets, whether they are CSS or JavaScript files, to WordPress sites and why you shouldn’t use other methods.
What is enqueueing, anyway?
Enqueueing is a user-friendly way of adding JavaScript and CSS files to WordPress sites. It provides a systematic method for loading these files. Through enqueueing, we can instruct WordPress when and where to load these assets, and also specify any dependencies between files.
Furthermore, this method allows everyone to use the same JavaScript libraries that come with the WordPress installation, from theme developers to plugin developers. This way, we avoid redundant loading of third-party scripts, which can lead to performance issues on your site and conflicts with the theme or plugins you are using.
Consider this: many plugins use the jQuery library. If each of these plugins loads jQuery from a different source, it can create chaos and cause JavaScript errors on your site.
So, in the context of enqueueing in WordPress, we’re talking about two central functions:
- The function wp_enqueue_script allows you to enqueue scripts (JavaScript files).
- The function wp_enqueue_style allows you to enqueue stylesheets (CSS files).
Before we delve deeper into these functions and their parameters, let’s look at a basic example of using wp_enqueue_script to add a JavaScript file to a WordPress site. The following function will load a file named my-script.js located in the main directory of the theme you’re using (if it exists).
function my_assets() {
wp_enqueue_script( 'theme-scripts', get_stylesheet_directory_uri() . '/my-script.js', array(), '1.0', true );
}
add_action( 'wp_enqueue_scripts', 'my_assets' );Enqueueing in Depth
Let’s take a look at the available parameters for these functions. Note that both of them take five parameters, with the first four being identical:
wp_enqueue_script( $handle, $source, $dependencies, $version, $args );
wp_enqueue_style( $handle, $source, $dependencies, $version, $media );- handle – A unique name for the asset. It’s recommended to use lowercase letters only.
- source – The URL of the asset. Make sure to use functions like
get_template_directory_uriandplugins_uri. - dependencies – An array of handles for assets that your asset depends on. The assets listed here will be loaded before the asset you’re adding.
- version – A version number to ensure the correct version is loaded, regardless of caching.
- args – This parameter is specific to
wp_enqueue_script. An array of additional script loading strategies. Otherwise, it may be a boolean in which case it determines whether the script is printed in the footer. More info. - media – This parameter is specific to
wp_enqueue_style. It allows you to specify the media type for which the CSS file is intended, e.g., screens, print, handheld…
Proper Use of Enqueueing for Adding Assets
As we haven’t mentioned, the ultimate result of enqueueing will be standard script or link tags in the page’s source code.
Let’s briefly consider the following example, which we’ll refer to as Example A. This code loads three JavaScript files and two CSS files in a standard HTML page:
<!DOCTYPE html>
<head>
<script type='text/javascript' src='jquery.js'>
<script type='text/javascript' src='owl.carousel.js'></script>
<link rel='stylesheet' type='text/css' href='reset.css'>
<link rel='stylesheet' type='text/css' href='style.css'>
</head>
<body>
<!-- Website content here-->
<script type='text/javascript' src='website-scripts.js'></script>
</body>
</html>Functionally, this code is valid and works fine. However, in a standard WordPress site, more scripts and CSS files are typically loaded than what you see in this example. There could be additional assets loaded by plugins or by the theme itself.
Given the importance of the loading order of these files, manually adding them to the Header or Footer can quickly become confusing. As mentioned, enqueueing is a method that lets you specify which assets to load, where to load them (in the Header or Footer), and whether there are any dependencies between files.
Let’s see how to add the assets in the above code to a WordPress site using enqueueing. This code should be placed in the functions.php file of the parent theme, a child theme, or any file in your plugin:
function my_assets() {
wp_enqueue_style( 'theme-style', get_stylesheet_uri(), array( 'reset' ) );
wp_enqueue_style( 'reset', get_stylesheet_directory_uri() . '/reset.css' );
wp_enqueue_script( 'owl-carousel', get_stylesheet_directory_uri() . '/owl.carousel.js', array( 'jquery' ) );
wp_enqueue_script( 'theme-scripts', get_stylesheet_directory_uri() . '/website-scripts.js', array( 'owl-carousel', 'jquery' ), '1.0', true );
}
add_action( 'wp_enqueue_scripts', 'my_assets' );Notice that a new function is introduced that we didn’t discuss before: wp_enqueue_style.
The first two files added in this code are CSS files. In terms of loading order, note that we called the style.css file before the reset.css file, despite the latter being dependent on the former. This is not a problem because we’ve defined the dependency between them in the third parameter.
The third asset we added is the Owl Carousel, which I really like because it allows you to create cool carousels. As you can see, in the third parameter of this file, we defined that this asset is dependent on jQuery and will be loaded after it.
No need to enqueue jQuery as it’s automatically loaded by WordPress.
The final script we added is theme-script. This script depends on both jQuery and Owl Carousel. Technically, we could have only specified the dependency on Owl Carousel since it depends on jQuery, and thus, the script we’re adding will be loaded after both of them anyway. However, I always prefer to explicitly list all dependencies for clarity when looking at the code.
The fourth parameter is optional and indicates the version of the script we set to 1.0. In general, the version of the script or CSS file allows us to perform cache busting after changes in the code.
The last parameter is to ensure that the script in question (theme-script) is loaded in the footer, and therefore the fifth parameter is set to true.
So, it can be understood that you don’t need to worry about the order of the assets. In other words, you can change the order of lines 2-6, and the code will work exactly the same.
Registering Assets
In practice, we skipped one step in the enqueuing process. Technically, we first need to register assets using wp_register_script, and only then enqueue them.
Registration allows WordPress to be aware of those assets, while enqueueing actually adds them to your site. Here’s an alternative version of adding Owl Carousel:
function my_assets() {
wp_register_script( 'owl-carousel', get_stylesheet_directory_uri() . '/owl.carousel.js', array( 'jquery' ) );
wp_enqueue_script( 'owl-carousel' );
}
add_action( 'wp_enqueue_scripts', 'my_assets' );However, the wp_enqueue_script() function performs the registration itself if you haven’t done it yourself. So, why use two functions when one is enough?
The answer is that in certain cases, you don’t want to load the asset in the same place where you registered it, and an excellent example of this is shortcodes.
Suppose you created a shortcode that requires JavaScript. If you enqueue it and assign it to the wp_enqueue_scripts hook as shown above (line 6), it will be loaded on every page of your site, even when that shortcode is not in use.
So the idea is to register the asset using wp_register_script but enqueue it within the shortcode function, so that the asset is loaded only when the shortcode is used. Furthermore, if you use the same shortcode multiple times in different places on a page, the asset will be loaded only once, thus covering us in this aspect as well.
To conclude this section, note that the functions wp_register_scripts and wp_register_styles share the same parameters as their enqueueing counterparts. However, if you decide to register, you can add only the handle when using wp_enqueue_script.
Removing Assets
WordPress also provides dequeueing functions that allow you to remove the loading of files and assets from themes or plugins:
wp_deregister_script()wp_deregister_style()wp_dequeue_script()wp_dequeue_style()
These functions allow you to modularly remove assets that are unnecessary from themes and plugins.
Summing Up
I believe you understand how important proper asset enqueueing is. The process removes the need for you to manage the dependencies between assets yourselves and allows you to add and manage them modularly.
Enqueueing is required in all WordPress themes and plugins. Your theme or plugin will not be approved in the WordPress repository and premium stores without using this process. It’s intended to “play nice” and prevent conflicts with plugins from other developers installed on your site, and it’s crucial for every WordPress developer to work this way.
If you enjoyed this article, I think you’ll find value in this guide that explains how to defer JavaScript in WordPress sites to improve loading times. Feel free to leave a comment below… 🙂
