5 Best Practices to Enqueuing Files in WordPress

by Woei Yu, April 9, 2015

You know that when you want to add style sheets or script files (eg JavaScript) to your WordPress blog, the right way is by enqueuing them. This allows you to not only add the relevant files dynamically and to not add something that is already being loaded but also to filter when you want it loaded.

There’s plenty of documentation on how to actually enqueue style sheets or script files. So I won’t waste your, nor my, time going through what so many others have already hashed over.

What I really want to delve into is the best practices on enqueuing style sheets and scripts because it is common for people to unknowingly miss one or more of them.

Below are the WordPress functions to enqueue a script and a style sheet and, as you can see, each function has arguments that can be used to specify how that file is enqueued.

Best Practice 1: Use Handle Names

In both enqueuing functions, the first argument is the name of the handle.

The handle name is only for the current enqueue action and it how you can refer to it later in the code; it must be unique to avoid any kind of conflict.

This is such an obvious one that I am embarrassed to put it in but sad to say, I’ve seen many situations where it wasn’t defined properly due to ignorance of the necessity for making it unique, laziness, or just forgetfulness.

So for the sake of completeness, here it is.

As a best practice, you should always prefix the handle name with the name of your theme or plugin.

For example, if my plugin name is MyAwesomePlugin and I want to insert a style sheet “sidebar.css”, I would create a handle named “MyAwesomePlugin_Sidebar” or “MyAwesomePlugin_Sidebar_Styling”.

Best Practice  2: Load Only What You Need When You Need It

Remember, the true power of enqueueing files lies in making files load conditionally. In other words, load files if, and only if, they are needed. Never bog down the page by loading in scripts and style sheets that are not going to be used.

Whether a file should or should not be included can be answered by knowing what sort of content the file will be used on. I always like to check out the Conditional Tags from WordPress Codex to help me narrow the field.

For example, if a script is only meant for the search result page, then use the following condition:

In my experience, many of scripts are rarely necessary on every single post and page and sometimes not at all (for example, if they’re used in the admin area).

So, if you can create filters then do so. You can create conditional filters for many situations, even crazy ones like for a single post with the title “Nectarine” or “Mango”, it as easy to do as:

You may also be surprised that there are a lot of scripts already registered, and some of them are already enqueued by WordPress, including the ubiquitous jQuery and jQuery UI library. These are listed in WordPress Codex.

Before you start enqueuing scripts, take a couple of minutes to check out the list. It is a pretty extensive list that covers a large range of functionality you can simply call in.

Having worked on dozens of WordPress sites and torn apart numerous themes and plugins, I am constantly amazed and horrified by how astronomically bloated a typical WordPress blog is. And improperly enqueued files, and/or files just added and not enqueued, is one of the biggest culprits.

On a side note, there is an argument to be made that the more files there are, the higher the number of HTTP requests made and that can significantly slow down the page load time.

That may be a show stopper in the past but in this day and age with technology like cloud services, minify software and caching plugins like WP-Rocket and W3 Total Cache , I’d rather sacrifice any perceived load time delay (if there is any after the above technologies) to get the ease and clarity of multiple files.

So before you start enqueuing files, sit down and take a couple of minutes to check out the Conditional Tags and the included script library.

Best Practice 3: Use Dependencies Whenever Possible

Dependencies are one of the most underutilized and yet most powerful things about WordPress’ enqueuing.

Experienced designers or developers know that when it comes to creating style sheets or scripts, it is easier create and maintain smaller, multiple files instead of one giant file. The number of files usually depends on how complex or how big the site/theme/plugin is.

Aside from it being easier for the designer or developers to manage, it also allows you to leave out CSS or script code on certain pages that don’t need them.

As a best practice, I always register the main style sheet or script file and, if the situation calls for it, I will enqueue a custom style sheet or script file and make sure I define my main files as my dependencies.

Registering a script or style sheet is very similar to enqueuing them:

And by making the file dependent on another one, what actually happens is the dependent file is loaded after the main file. For example, by making sidebar.css dependent on the main style sheet, the main style sheet is loaded first and then the sidebar.css is loaded second.

Best Practice 4: Always Define a File Version

This is the fourth argument in the enqueue and register functions.

A lot of designers and developers leave this blank which is a horrible mistake to make.

Most, if not all browsers, cache style sheet or script files and there are a lot of websites that use some form of server caching that will cache these files too. So, even if you make an update to your files, the browser and potentially the server will still serve up the old version of the style sheet or script files.

So, by changing the version number, you’re guaranteed that the updated file will be sent to the person’s web browser. The trick I like to use is to include the theme or plugin version number as the file version of the files I enqueue.

Personally, I like to put my plugin version or theme version as a constant in a config file and then I can update any of my scripts or style sheets without modifying the actual code.

Best Practice 5: Load Your Scripts at the Bottom of the Page

When enqueuing scripts, you have the option of either enqueuing script files in the header or the footer of the page. Frankly, 99% of the time, a script has no actual use until the HTML has finished loading so there is no reason why you shouldn’t always put it at the bottom.

This is especially significant because web browsers download no more than about 4 components in parallel per domain name and, if you have images or style sheet or script files on your page, you can get no more than the maximum downloads occurring simultaneously.

In essence, if your scripts are at the top of the page, the browser will stop and download those scripts before continuing to process the page.

If you have a couple of small script files, users probably won’t notice any delay but if you are talking about 10-20 script files (remember other plugins and the theme may have their own enqueued files) the viewers will see a blank screen because the browser is spending precious seconds downloading the scripts first.

By putting the scripts at the bottom, you are getting your HTML and CSS to your users as quick as possible and the page appears to load much more quickly.

The main disadvantage of putting scripts at the bottom of the page is that the page will render before the scripts have run, and impatient clickers (like myself) will interact with your site before the JavaScript is ready.

Sometimes there are parts of the page that won’t look right without JavaScript and a trick I like to use it to put a CSS display:none on those elements and in my script file (which I place at the bottom) I’ll enable and display them once the download is complete.



So these are the top 5 best practices to use whenever you add style sheets and scripts into WordPress.

It really doesn’t take much effort to code efficiently from the ground up, to make things fast and efficient for the users.

Over the past few years, it has become much easier to create and deploy themes and plugins. WordPress itself has grown as well, offering more features out of the box and providing hooks and APIs for themes and plugins to expand further on that.

Because of the popularity and the ease of use, sites are getting bloated, cumbersome and hard to adjust, so, as developers, we have a responsibility to not only make sure that our sites are usable for our visitors and that our code to be clean and efficient.

We can do better. We should do better.

No Comments

Leave a Reply

Your email address will not be published Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">


Let me know what you think

Follow by Email


Enjoy this article? Please spread the word :)