How to Properly Add jQuery Scripts to WordPress
Despite the fact WordPress has been around for a while, and the method of adding scripts to themes and plugins has been the same for years, there is still some confusion around how exactly you’re supposed to add scripts. So let’s clear it up.
jQuery’s Compatibility Mode
Before we start attaching scripts to WordPress, let’s look at jQuery’s compatibility mode. WordPress comes pre-packaged with a copy of jQuery, which you should use with your code. When WordPress’ jQuery is loaded, it uses compatibility mode, which is a mechanism for avoiding conflicts with other language libraries.
What this boils down to is that you can’t use the dollar sign directly as you would in other projects. When writing jQuery for WordPress you need to use
jQuery instead. Take a look at the code below to see what I mean:
The good news is that with a few modifications you can go back to the lovely little dollar sign once again! Writing jQuery out so many times makes the code longer to write and more difficult to read.
Just to recap if you’re learning jQuery, the $ sign is just an alias to jQuery(), then an alias to a function. The basic syntax is:
- A dollar sign to define jQuery
- A (selector) to “query (or find)” HTML elements
- A jQuery action() to be performed on the element(s)
If you’re loading your script in the footer, you can wrap your code in an anonymous function, which will map jQuery to
$. Here’s how:
If you want to add your script in the header – which you should avoid if possible – you can wrap everything in a document-ready function, passing
$ along the way.
Linking Your jQuery Scripts
Now that you can write valid jQuery code for WordPress, let’s link our work to our website. In WordPress the process is called enqueueing. For a regular HTML website, we would use the
<link> element to add scripts.
WordPress ends up doing the same thing, but we’ll use special WordPress functions to achieve it. This way, WordPress handles all our dependencies for us – thanks, WordPress!
If you’re working on a theme, you can use the
wp_enqueue_script() function within your
functions.php file. Here’s how.
The function takes five arguments. The first is a handle you can use to refer to the script, the second is the location of the script file, the third parameter is an array of dependencies.
I’ve added jQuery as a dependency since the script uses it. If you create a script that depends on “my-great-script,” you should add it to the dependency list so WordPress knows which files to load first.
The fourth parameter is a version number and the fifth lets WordPress know where to put the script. By default, scripts will be loaded in the header, which is bad practice and will slow down the page loading of your site (browsers halt all loading whenever a
Adding Scripts to the WordPress Admin
You can also add scripts to the admin. The functions used are exactly the same, you just need to use a different hook. Take a look at the example below:
Instead of hooking into
wp_enqueue_scripts we need to use
admin_enqueue_scripts. That’s it!
Using Conditional Tags
Use conditional tags to only load your scripts when necessary. This is more often used in the admin where you would want to use a script only on a specific page, not the whole admin. This saves bandwidth and processing time, which means faster loading times for your website.
Take a look at the admin_enqueue_scripts documentation in the WordPress Codex for more information.
Adding simple jQuery scripts to WordPress is not difficult at all once you know how. There is a little bit of an overhead compared to doing it in vanilla HTML, but there is also the added benefit of dependency management and clarity.
Do you use jQuery on your site? What other jQuery tips and tricks would you like to see on our blog? Let us know in the comments below.